From fe2341f2f6bb20f4137d2e2889ea351516edc615 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Thu, 3 Aug 2023 01:14:26 +1000 Subject: [PATCH 01/85] feat(rest-middleware): initial work for rest API middleware --- .../event_handler/api_gateway.py | 103 ++++++++++++++++-- .../event_handler/middleware/__init__.py | 3 + .../middleware/registered_api.py | 20 ++++ 3 files changed, 115 insertions(+), 11 deletions(-) create mode 100644 aws_lambda_powertools/event_handler/middleware/__init__.py create mode 100644 aws_lambda_powertools/event_handler/middleware/registered_api.py diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 7f86293fb4a..c83a7fa3e52 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -25,6 +25,7 @@ from aws_lambda_powertools.event_handler import content_types from aws_lambda_powertools.event_handler.exceptions import NotFoundError, ServiceError +from aws_lambda_powertools.event_handler.middleware import registered_api_middleware from aws_lambda_powertools.shared.cookies import Cookie from aws_lambda_powertools.shared.functions import powertools_dev_is_set from aws_lambda_powertools.shared.json_encoder import Encoder @@ -210,6 +211,8 @@ def __init__( class Route: """Internally used Route Configuration""" + _middleware_built = False + def __init__( self, method: str, @@ -218,6 +221,7 @@ def __init__( cors: bool, compress: bool, cache_control: Optional[str], + middleware: Optional[List[Callable]], ): self.method = method.upper() self.rule = rule @@ -225,6 +229,23 @@ def __init__( self.cors = cors self.compress = compress self.cache_control = cache_control + self.middleware = middleware or [] + + def __call__(self, app, args: Dict[str, str]): + """Builds the middleware stack using global and route middlewares, redefining the original handler function""" + if not self._middleware_built: + all_middleware = list(self.middleware) + + # IMPORTANT: # this must be the last mdidleware in the stack to avoid breaking changes + # for the registered API call signature (Maintain Backward Compatibility) + all_middleware.append(registered_api_middleware) + + for handler in reversed(all_middleware): + self.func = MiddlewareHandler(handler=handler, next_handler=self.func) + + self._middleware_built = True + + return self.func(app, **args) class ResponseBuilder: @@ -322,6 +343,7 @@ class BaseRouter(ABC): current_event: BaseProxyEvent lambda_context: LambdaContext context: dict + middleware: List[Callable] = [] @abstractmethod def route( @@ -331,10 +353,21 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, + middleware: Optional[List[Callable]] = None, ): raise NotImplementedError() - def get(self, rule: str, cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None): + def use(self, middleware: List[Callable]): + self.middleware.append(middleware) + + def get( + self, + rule: str, + cors: Optional[bool] = None, + compress: bool = False, + cache_control: Optional[str] = None, + middleware: Optional[List[Callable]] = None, + ): """Get route decorator with GET `method` Examples @@ -357,9 +390,16 @@ def lambda_handler(event, context): return app.resolve(event, context) ``` """ - return self.route(rule, "GET", cors, compress, cache_control) + return self.route(rule, "GET", cors, compress, cache_control, middleware) - def post(self, rule: str, cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None): + def post( + self, + rule: str, + cors: Optional[bool] = None, + compress: bool = False, + cache_control: Optional[str] = None, + middleware: Optional[List[Callable]] = None, + ): """Post route decorator with POST `method` Examples @@ -383,9 +423,16 @@ def lambda_handler(event, context): return app.resolve(event, context) ``` """ - return self.route(rule, "POST", cors, compress, cache_control) + return self.route(rule, "POST", cors, compress, cache_control, middleware) - def put(self, rule: str, cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None): + def put( + self, + rule: str, + cors: Optional[bool] = None, + compress: bool = False, + cache_control: Optional[str] = None, + middleware: Optional[List[Callable]] = None, + ): """Put route decorator with PUT `method` Examples @@ -409,7 +456,7 @@ def lambda_handler(event, context): return app.resolve(event, context) ``` """ - return self.route(rule, "PUT", cors, compress, cache_control) + return self.route(rule, "PUT", cors, compress, cache_control, middleware) def delete( self, @@ -417,6 +464,7 @@ def delete( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, + middleware: Optional[List[Callable]] = None, ): """Delete route decorator with DELETE `method` @@ -440,7 +488,7 @@ def lambda_handler(event, context): return app.resolve(event, context) ``` """ - return self.route(rule, "DELETE", cors, compress, cache_control) + return self.route(rule, "DELETE", cors, compress, cache_control, middleware) def patch( self, @@ -448,6 +496,7 @@ def patch( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, + middleware: Optional[List[Callable]] = None, ): """Patch route decorator with PATCH `method` @@ -474,7 +523,7 @@ def lambda_handler(event, context): return app.resolve(event, context) ``` """ - return self.route(rule, "PATCH", cors, compress, cache_control) + return self.route(rule, "PATCH", cors, compress, cache_control, middleware) def append_context(self, **additional_context): """Append key=value data as routing context""" @@ -485,6 +534,21 @@ def clear_context(self): self.context.clear() +class MiddlewareHandler: + """Represents a callable Middleware function used to build a middleware stack when a route is resolved""" + + def __init__( + self, + handler: Callable[..., Any], + next_handler: Callable[..., Any], + ) -> None: + self.handler: Callable[..., Any] = handler + self.next_handler: Callable[..., Any] = next_handler + + def __call__(self, app: BaseRouter, **kwargs) -> Any: + return self.handler(app, self.next_handler, **kwargs) + + class ApiGatewayResolver(BaseRouter): """API Gateway and ALB proxy resolver @@ -561,6 +625,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, + middleware: Optional[List[Callable]] = None, ): """Route decorator includes parameter `method`""" @@ -573,7 +638,7 @@ def register_resolver(func: Callable): cors_enabled = cors for item in methods: - _route = Route(item, self._compile_regex(rule), func, cors_enabled, compress, cache_control) + _route = Route(item, self._compile_regex(rule), func, cors_enabled, compress, cache_control, middleware) # The more specific route wins. # We store dynamic (/studies/{studyid}) and static routes (/studies/fetch) separately. @@ -768,7 +833,7 @@ def _not_found(self, method: str) -> ResponseBuilder: def _call_route(self, route: Route, args: Dict[str, str]) -> ResponseBuilder: """Actually call the matching route with any provided keyword arguments.""" try: - return ResponseBuilder(self._to_response(route.func(**args)), route) + return ResponseBuilder(self._to_response(route(app=self, args=args)), route) except Exception as exc: response_builder = self._call_exception_handler(exc, route) if response_builder: @@ -895,6 +960,7 @@ class Router(BaseRouter): def __init__(self): self._routes: Dict[tuple, Callable] = {} + self._routes_with_middleware: Dict[tuple, List[Callable]] = {} self.api_resolver: Optional[BaseRouter] = None self.context = {} # early init as customers might add context before event resolution @@ -905,11 +971,25 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, + middleware: Optional[List[Callable]] = None, ): def register_route(func: Callable): # Convert methods to tuple. It needs to be hashable as its part of the self._routes dict key methods = (method,) if isinstance(method, str) else tuple(method) - self._routes[(rule, methods, cors, compress, cache_control)] = func + + tuple_key = (rule, methods, cors, compress, cache_control) + + # Collate Middleware for routes + if middleware is not None: + for handler in middleware: + self._routes_with_middleware[tuple_key] = self._routes_with_middleware.get(tuple_key, []).append( + handler, + ) + else: + self._routes_with_middleware[tuple_key] = [] + + self._routes[tuple_key] = func + return func return register_route @@ -933,6 +1013,7 @@ def route( self, rule: str, method: Union[str, Union[List[str], Tuple[str]]], + middleware: Optional[List[Callable]] = None, cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, diff --git a/aws_lambda_powertools/event_handler/middleware/__init__.py b/aws_lambda_powertools/event_handler/middleware/__init__.py new file mode 100644 index 00000000000..91a60a9aac8 --- /dev/null +++ b/aws_lambda_powertools/event_handler/middleware/__init__.py @@ -0,0 +1,3 @@ +from aws_lambda_powertools.event_handler.middleware.registered_api import registered_api_middleware + +__all__ = ["registered_api_middleware"] diff --git a/aws_lambda_powertools/event_handler/middleware/registered_api.py b/aws_lambda_powertools/event_handler/middleware/registered_api.py new file mode 100644 index 00000000000..ae75fea3d83 --- /dev/null +++ b/aws_lambda_powertools/event_handler/middleware/registered_api.py @@ -0,0 +1,20 @@ +import logging +from typing import Callable + +logger = logging.getLogger(__name__) + + +def registered_api_middleware(app, get_response: Callable, **kwargs): + """ + Call the registered API using the **kwargs provided. + + :param app: The API Gateway resolver + :param get_response: The function to handle the API + :param kwargs: The arguments to pass to the API + :return: The API Response Object + + This middleware enables backward compatibility for existing API routes + """ + logger.debug(f"Calling registered API with kwargs: {kwargs}") + + return app._to_response(get_response(**kwargs)) From 4cfa87df2e407acb6e69dab6370564b4cb654e16 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Thu, 3 Aug 2023 10:21:51 +1000 Subject: [PATCH 02/85] feat(rest-middlware): Add in Router based middleware and add Middleware for Cors and Compression as examples --- .../event_handler/api_gateway.py | 21 +- .../event_handler/middleware/__init__.py | 4 +- .../event_handler/middleware/cache_control.py | 20 ++ .../event_handler/middleware/compression.py | 20 ++ .../event_handler/middleware/cors.py | 19 ++ .../middleware/registered_api.py | 6 +- .../event_handler/test_api_gateway.py | 209 ++++++++++++++++++ 7 files changed, 286 insertions(+), 13 deletions(-) create mode 100644 aws_lambda_powertools/event_handler/middleware/cache_control.py create mode 100644 aws_lambda_powertools/event_handler/middleware/compression.py create mode 100644 aws_lambda_powertools/event_handler/middleware/cors.py diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index c83a7fa3e52..23ac7de9f19 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -25,7 +25,7 @@ from aws_lambda_powertools.event_handler import content_types from aws_lambda_powertools.event_handler.exceptions import NotFoundError, ServiceError -from aws_lambda_powertools.event_handler.middleware import registered_api_middleware +from aws_lambda_powertools.event_handler.middleware.registered_api import registered_api_middleware from aws_lambda_powertools.shared.cookies import Cookie from aws_lambda_powertools.shared.functions import powertools_dev_is_set from aws_lambda_powertools.shared.json_encoder import Encoder @@ -231,10 +231,11 @@ def __init__( self.cache_control = cache_control self.middleware = middleware or [] - def __call__(self, app, args: Dict[str, str]): + def __call__(self, router_middleware: List[Callable], app, args: Dict[str, str]): """Builds the middleware stack using global and route middlewares, redefining the original handler function""" if not self._middleware_built: - all_middleware = list(self.middleware) + # prepend global router middleware first + all_middleware = list(router_middleware) + list(self.middleware) # IMPORTANT: # this must be the last mdidleware in the stack to avoid breaking changes # for the registered API call signature (Maintain Backward Compatibility) @@ -343,7 +344,7 @@ class BaseRouter(ABC): current_event: BaseProxyEvent lambda_context: LambdaContext context: dict - middleware: List[Callable] = [] + router_middleware: List[Callable] = [] @abstractmethod def route( @@ -357,8 +358,11 @@ def route( ): raise NotImplementedError() - def use(self, middleware: List[Callable]): - self.middleware.append(middleware) + def use(self, middleware: Union[Callable, List[Callable]]): + """Add a middleware to the router""" + if not isinstance(middleware, list): + middleware = [middleware] + self.router_middleware = list(self.router_middleware) + list(middleware) def get( self, @@ -833,7 +837,10 @@ def _not_found(self, method: str) -> ResponseBuilder: def _call_route(self, route: Route, args: Dict[str, str]) -> ResponseBuilder: """Actually call the matching route with any provided keyword arguments.""" try: - return ResponseBuilder(self._to_response(route(app=self, args=args)), route) + return ResponseBuilder( + self._to_response(route(router_middleware=self.router_middleware, app=self, args=args)), + route, + ) except Exception as exc: response_builder = self._call_exception_handler(exc, route) if response_builder: diff --git a/aws_lambda_powertools/event_handler/middleware/__init__.py b/aws_lambda_powertools/event_handler/middleware/__init__.py index 91a60a9aac8..d85b68d06fd 100644 --- a/aws_lambda_powertools/event_handler/middleware/__init__.py +++ b/aws_lambda_powertools/event_handler/middleware/__init__.py @@ -1,3 +1 @@ -from aws_lambda_powertools.event_handler.middleware.registered_api import registered_api_middleware - -__all__ = ["registered_api_middleware"] +# Unable to import specific modules due to Cyclic dependency created with api_gateway.py module :-( diff --git a/aws_lambda_powertools/event_handler/middleware/cache_control.py b/aws_lambda_powertools/event_handler/middleware/cache_control.py new file mode 100644 index 00000000000..00eca1abe64 --- /dev/null +++ b/aws_lambda_powertools/event_handler/middleware/cache_control.py @@ -0,0 +1,20 @@ +from typing import Callable, Optional + +from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response + + +class CacheControlMiddleware: + def __init__(self, cache_control: Optional[str] = None): + self.cache_control = cache_control + + def __call__(self, app: ApiGatewayResolver, get_response: Callable, **kwargs) -> Response: + # Modify request details here before calling handler + + # Call Handler and get response + result: Response = get_response(app, **kwargs) + + # Modify Response from Handler here before returning + cache_control = self.cache_control if result.status_code == 200 else "no-cache" + result.headers["Cache-Control"] = cache_control + + return result diff --git a/aws_lambda_powertools/event_handler/middleware/compression.py b/aws_lambda_powertools/event_handler/middleware/compression.py new file mode 100644 index 00000000000..0fc593469a1 --- /dev/null +++ b/aws_lambda_powertools/event_handler/middleware/compression.py @@ -0,0 +1,20 @@ +from typing import Callable, Optional + +from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response + + +class CompressionMiddleware: + def __init__(self, cache_control: Optional[str] = None): + self.cache_control = cache_control + + def __call__(self, app: ApiGatewayResolver, get_response: Callable, **kwargs) -> Response: + # Modify request details here before calling handler + + # Call Handler and get response + result: Response = get_response(app, **kwargs) + + # Modify Response from Handler here before returning + cache_control = self.cache_control if result.status_code == 200 else "no-cache" + result.headers["Cache-Control"] = cache_control + + return result diff --git a/aws_lambda_powertools/event_handler/middleware/cors.py b/aws_lambda_powertools/event_handler/middleware/cors.py new file mode 100644 index 00000000000..e687f572004 --- /dev/null +++ b/aws_lambda_powertools/event_handler/middleware/cors.py @@ -0,0 +1,19 @@ +from typing import Callable, Optional + +from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, CORSConfig, Response + + +class CORSMiddleware: + def __init__(self, config: Optional[CORSConfig] = None): + self.cors = config or CORSConfig() + + def __call__(self, app: ApiGatewayResolver, get_response: Callable, **kwargs) -> Response: + # Modify request details here before calling handler + + # Call Handler and get response + result: Response = get_response(app, **kwargs) + + # Modify Response from Handler here before returning + result.headers.update(self.cors.to_dict(app.current_event.get_header_value("Origin"))) + + return result diff --git a/aws_lambda_powertools/event_handler/middleware/registered_api.py b/aws_lambda_powertools/event_handler/middleware/registered_api.py index ae75fea3d83..0e292259dfa 100644 --- a/aws_lambda_powertools/event_handler/middleware/registered_api.py +++ b/aws_lambda_powertools/event_handler/middleware/registered_api.py @@ -4,6 +4,7 @@ logger = logging.getLogger(__name__) +# Note: Type hinting not available due to cyclic dependency between api_gateway.py and this module def registered_api_middleware(app, get_response: Callable, **kwargs): """ Call the registered API using the **kwargs provided. @@ -13,8 +14,7 @@ def registered_api_middleware(app, get_response: Callable, **kwargs): :param kwargs: The arguments to pass to the API :return: The API Response Object - This middleware enables backward compatibility for existing API routes + This middleware enables backward compatibility for the existing API routes model in Powertools + and it MUST be the final middleware in the middleware stack. """ - logger.debug(f"Calling registered API with kwargs: {kwargs}") - return app._to_response(get_response(**kwargs)) diff --git a/tests/functional/event_handler/test_api_gateway.py b/tests/functional/event_handler/test_api_gateway.py index 2afd1241bed..422107f9199 100644 --- a/tests/functional/event_handler/test_api_gateway.py +++ b/tests/functional/event_handler/test_api_gateway.py @@ -30,6 +30,8 @@ ServiceError, UnauthorizedError, ) +from aws_lambda_powertools.event_handler.middleware.cache_control import CacheControlMiddleware +from aws_lambda_powertools.event_handler.middleware.cors import CORSMiddleware from aws_lambda_powertools.shared import constants from aws_lambda_powertools.shared.cookies import Cookie from aws_lambda_powertools.shared.json_encoder import Encoder @@ -1749,3 +1751,210 @@ def static_handler() -> Response: # THEN the static_handler should have been called, because it fully matches the path directly response_body = json.loads(response["body"]) assert response_body["hello"] == "static" + + +def test_route_with_middleware(): + # GIVEN a Rest API Gateway proxy type event + app = ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent) + + # define custom middleware to inject new argument - "custom" + def middleware_1(app, get_response, **kwargs): + # inject a variable into the kwargs + response = get_response(app, custom="custom", **kwargs) + + return response + + # define custom middleware to inject new argument - "another_one" + def middleware_2(app, get_response, **kwargs): + # inject a variable into the kwargs + response = get_response(app, another_one=6, **kwargs) + + return response + + @app.get("/my/path", middleware=[middleware_1, middleware_2]) + def get_lambda(another_one: int, custom: str) -> Response: + assert isinstance(app.current_event, APIGatewayProxyEvent) + assert another_one == 6 + assert custom == "custom" + return Response(200, content_types.TEXT_HTML, "foo") + + # WHEN calling the event handler + result = app(LOAD_GW_EVENT, {}) + + # THEN process event correctly + # AND set the current_event type as APIGatewayProxyEvent + assert result["statusCode"] == 200 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] + assert result["body"] == "foo" + + +def test_with_router_middleware(): + # GIVEN a Rest API Gateway proxy type event + app = ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent) + + # define custom middleware to inject new argument - "custom" + def middleware_1(app, get_response, **kwargs): + # inject a variable into the kwargs + response = get_response(app, custom="custom", **kwargs) + + return response + + # define custom middleware to inject new argument - "another_one" + def middleware_2(app, get_response, **kwargs): + # inject a variable into the kwargs + response = get_response(app, another_one=6, **kwargs) + + return response + + app.use([middleware_1, middleware_2]) + + @app.get("/my/path") + def get_lambda(another_one: int, custom: str) -> Response: + assert isinstance(app.current_event, APIGatewayProxyEvent) + assert another_one == 6 + assert custom == "custom" + return Response(200, content_types.TEXT_HTML, "foo") + + # WHEN calling the event handler + result = app(LOAD_GW_EVENT, {}) + + # THEN process event correctly + # AND set the current_event type as APIGatewayProxyEvent + assert result["statusCode"] == 200 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] + assert result["body"] == "foo" + + +def test_dynamic_route_with_middleware(): + # GIVEN + app = ApiGatewayResolver() + + def middleware_one(app, get_response, **kwargs): + # inject a variable into the kwargs + response = get_response(app, injected="injected_value", **kwargs) + + return response + + @app.get("//", middleware=[middleware_one]) + def get_lambda(my_id: str, name: str, injected: str) -> Response: + assert name == "my" + assert injected == "injected_value" + + return Response(200, content_types.TEXT_HTML, my_id) + + # WHEN calling the event handler + result = app(LOAD_GW_EVENT, {}) + + # THEN + assert result["statusCode"] == 200 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] + assert result["body"] == "path" + + +def test_route_cors_middleware(): + # GIVEN a function with cors middleware (class definition) + # AND http method set to GET + app = ApiGatewayResolver() + + @app.get("/my/path", middleware=[CORSMiddleware()]) + def with_cors() -> Response: + return Response(200, content_types.TEXT_HTML, "test") + + @app.get("/without-cors") + def without_cors() -> Response: + return Response(200, content_types.TEXT_HTML, "test") + + def handler(event, context): + return app.resolve(event, context) + + # WHEN calling the event handler + result = handler(LOAD_GW_EVENT, None) + + # THEN the headers should include cors headers + assert "multiValueHeaders" in result + headers = result["multiValueHeaders"] + assert headers["Content-Type"] == [content_types.TEXT_HTML] + assert headers["Access-Control-Allow-Origin"] == ["https://aws.amazon.com"] + assert "Access-Control-Allow-Credentials" not in headers + assert headers["Access-Control-Allow-Headers"] == [",".join(sorted(CORSConfig._REQUIRED_HEADERS))] + + # THEN for routes without cors flag return no cors headers + mock_event = {"path": "/my/request", "httpMethod": "GET"} + result = handler(mock_event, None) + assert "Access-Control-Allow-Origin" not in result["multiValueHeaders"] + + +def test_router_cors_middleware(): + # GIVEN a function with cors middleware (class definition) + # AND http method set to GET + app = ApiGatewayResolver() + app.use(CORSMiddleware()) + + @app.get("/my/path") + def with_cors() -> Response: + return Response(200, content_types.TEXT_HTML, "test") + + @app.get("/without-cors") + def without_cors() -> Response: + return Response(200, content_types.TEXT_HTML, "test") + + def handler(event, context): + return app.resolve(event, context) + + # WHEN calling the event handler + result = handler(LOAD_GW_EVENT, None) + + # THEN the headers should include cors headers + assert "multiValueHeaders" in result + headers = result["multiValueHeaders"] + assert headers["Content-Type"] == [content_types.TEXT_HTML] + assert headers["Access-Control-Allow-Origin"] == ["https://aws.amazon.com"] + assert "Access-Control-Allow-Credentials" not in headers + assert headers["Access-Control-Allow-Headers"] == [",".join(sorted(CORSConfig._REQUIRED_HEADERS))] + + # THEN for routes without cors flag return no cors headers + mock_event = {"path": "/my/request", "httpMethod": "GET"} + result = handler(mock_event, None) + assert "Access-Control-Allow-Origin" not in result["multiValueHeaders"] + + +def test_cache_control_middleware_200(): + # GIVEN a function with cache_control set + app = ApiGatewayResolver() + + @app.get("/success", middleware=[CacheControlMiddleware("max-age=600")]) + def with_cache_control() -> Response: + return Response(200, content_types.TEXT_HTML, "has 200 response") + + def handler(event, context): + return app.resolve(event, context) + + # WHEN calling the event handler + # AND the function returns a 200 status code + result = handler({"path": "/success", "httpMethod": "GET"}, None) + + # THEN return the set Cache-Control + headers = result["multiValueHeaders"] + assert headers["Content-Type"] == [content_types.TEXT_HTML] + assert headers["Cache-Control"] == ["max-age=600"] + + +def test_cache_control_middleware_non_200(): + # GIVEN a function with cache_control set + app = ApiGatewayResolver() + + @app.delete("/fails", middleware=[CacheControlMiddleware("max-age=600")]) + def with_cache_control_has_500() -> Response: + return Response(503, content_types.TEXT_HTML, "has 503 response") + + def handler(event, context): + return app.resolve(event, context) + + # WHEN calling the event handler + # AND the function returns a 503 status code + result = handler({"path": "/fails", "httpMethod": "DELETE"}, None) + + # THEN return a Cache-Control of "no-cache" + headers = result["multiValueHeaders"] + assert headers["Content-Type"] == [content_types.TEXT_HTML] + assert headers["Cache-Control"] == ["no-cache"] From 4e28b0635a9ab5c724744dff59e7a4dc03ecc4f4 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Thu, 3 Aug 2023 10:57:53 +1000 Subject: [PATCH 03/85] feat(api-middleware): remove compression middleware - not implemented yet --- .../event_handler/middleware/compression.py | 20 ------------------- 1 file changed, 20 deletions(-) delete mode 100644 aws_lambda_powertools/event_handler/middleware/compression.py diff --git a/aws_lambda_powertools/event_handler/middleware/compression.py b/aws_lambda_powertools/event_handler/middleware/compression.py deleted file mode 100644 index 0fc593469a1..00000000000 --- a/aws_lambda_powertools/event_handler/middleware/compression.py +++ /dev/null @@ -1,20 +0,0 @@ -from typing import Callable, Optional - -from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response - - -class CompressionMiddleware: - def __init__(self, cache_control: Optional[str] = None): - self.cache_control = cache_control - - def __call__(self, app: ApiGatewayResolver, get_response: Callable, **kwargs) -> Response: - # Modify request details here before calling handler - - # Call Handler and get response - result: Response = get_response(app, **kwargs) - - # Modify Response from Handler here before returning - cache_control = self.cache_control if result.status_code == 200 else "no-cache" - result.headers["Cache-Control"] = cache_control - - return result From edcc6f74a5b8c165f01b7e07ac3c93c2374db7b5 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Thu, 3 Aug 2023 23:38:28 +1000 Subject: [PATCH 04/85] fix(typing): resolve mypy errors --- aws_lambda_powertools/event_handler/api_gateway.py | 9 +++++---- .../event_handler/middleware/cache_control.py | 2 +- tests/functional/event_handler/test_api_gateway.py | 2 +- 3 files changed, 7 insertions(+), 6 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 23ac7de9f19..2ea095db60e 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -989,9 +989,10 @@ def register_route(func: Callable): # Collate Middleware for routes if middleware is not None: for handler in middleware: - self._routes_with_middleware[tuple_key] = self._routes_with_middleware.get(tuple_key, []).append( - handler, - ) + if self._routes_with_middleware.get(tuple_key) is None: + self._routes_with_middleware[tuple_key] = [handler] + else: + self._routes_with_middleware[tuple_key].append(handler) else: self._routes_with_middleware[tuple_key] = [] @@ -1020,10 +1021,10 @@ def route( self, rule: str, method: Union[str, Union[List[str], Tuple[str]]], - middleware: Optional[List[Callable]] = None, cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, + middleware: Optional[List[Callable]] = None, ): # NOTE: see #1552 for more context. return super().route(rule.rstrip("/"), method, cors, compress, cache_control) diff --git a/aws_lambda_powertools/event_handler/middleware/cache_control.py b/aws_lambda_powertools/event_handler/middleware/cache_control.py index 00eca1abe64..c2e323e826c 100644 --- a/aws_lambda_powertools/event_handler/middleware/cache_control.py +++ b/aws_lambda_powertools/event_handler/middleware/cache_control.py @@ -15,6 +15,6 @@ def __call__(self, app: ApiGatewayResolver, get_response: Callable, **kwargs) -> # Modify Response from Handler here before returning cache_control = self.cache_control if result.status_code == 200 else "no-cache" - result.headers["Cache-Control"] = cache_control + result.headers["Cache-Control"] = cache_control or "" return result diff --git a/tests/functional/event_handler/test_api_gateway.py b/tests/functional/event_handler/test_api_gateway.py index 422107f9199..66d1f9124ad 100644 --- a/tests/functional/event_handler/test_api_gateway.py +++ b/tests/functional/event_handler/test_api_gateway.py @@ -1879,7 +1879,7 @@ def handler(event, context): assert headers["Access-Control-Allow-Headers"] == [",".join(sorted(CORSConfig._REQUIRED_HEADERS))] # THEN for routes without cors flag return no cors headers - mock_event = {"path": "/my/request", "httpMethod": "GET"} + mock_event = {"path": "/without-cors", "httpMethod": "GET"} result = handler(mock_event, None) assert "Access-Control-Allow-Origin" not in result["multiValueHeaders"] From 2c67e1044827dfe688f5c80c5ac9a3f8861884e4 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 00:36:38 +1000 Subject: [PATCH 05/85] Update aws_lambda_powertools/event_handler/api_gateway.py Co-authored-by: Heitor Lessa Signed-off-by: walmsles <2704782+walmsles@users.noreply.github.com> --- aws_lambda_powertools/event_handler/api_gateway.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 2ea095db60e..bd2ea726617 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -229,7 +229,7 @@ def __init__( self.cors = cors self.compress = compress self.cache_control = cache_control - self.middleware = middleware or [] + self.middlewares = middlewares or [] def __call__(self, router_middleware: List[Callable], app, args: Dict[str, str]): """Builds the middleware stack using global and route middlewares, redefining the original handler function""" From 822f16be25724419f99ec33ce450c5eef8d6ef5b Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 00:38:11 +1000 Subject: [PATCH 06/85] Update aws_lambda_powertools/event_handler/api_gateway.py Co-authored-by: Heitor Lessa Signed-off-by: walmsles <2704782+walmsles@users.noreply.github.com> --- aws_lambda_powertools/event_handler/api_gateway.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index bd2ea726617..e26f2e6d24f 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -221,7 +221,7 @@ def __init__( cors: bool, compress: bool, cache_control: Optional[str], - middleware: Optional[List[Callable]], + middlewares: Optional[List[Callable]], ): self.method = method.upper() self.rule = rule From 51c3da5fc155932ec15c2a8f49046d6d9ba26d17 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 00:39:39 +1000 Subject: [PATCH 07/85] Update aws_lambda_powertools/event_handler/api_gateway.py Co-authored-by: Heitor Lessa Signed-off-by: walmsles <2704782+walmsles@users.noreply.github.com> --- aws_lambda_powertools/event_handler/api_gateway.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index e26f2e6d24f..8bc86317ec9 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -235,7 +235,7 @@ def __call__(self, router_middleware: List[Callable], app, args: Dict[str, str]) """Builds the middleware stack using global and route middlewares, redefining the original handler function""" if not self._middleware_built: # prepend global router middleware first - all_middleware = list(router_middleware) + list(self.middleware) + all_middlewares = router_middlewares + self.middlewares # IMPORTANT: # this must be the last mdidleware in the stack to avoid breaking changes # for the registered API call signature (Maintain Backward Compatibility) From 98da7dc68e37124720a926636764a9a4fac4bec2 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 00:40:24 +1000 Subject: [PATCH 08/85] Update aws_lambda_powertools/event_handler/api_gateway.py Co-authored-by: Heitor Lessa Signed-off-by: walmsles <2704782+walmsles@users.noreply.github.com> --- aws_lambda_powertools/event_handler/api_gateway.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 8bc86317ec9..aa22b41b276 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -344,7 +344,7 @@ class BaseRouter(ABC): current_event: BaseProxyEvent lambda_context: LambdaContext context: dict - router_middleware: List[Callable] = [] + router_middlewares: List[Callable] = [] @abstractmethod def route( From d775bba58ca02d61d65334daff8db87143462ca4 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 00:40:43 +1000 Subject: [PATCH 09/85] Update aws_lambda_powertools/event_handler/api_gateway.py Co-authored-by: Heitor Lessa Signed-off-by: walmsles <2704782+walmsles@users.noreply.github.com> --- aws_lambda_powertools/event_handler/api_gateway.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index aa22b41b276..68ae1b304ef 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -354,7 +354,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middleware: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable]] = None, ): raise NotImplementedError() From d12fa20cf1ce2bc0ae1400304dd938b8b8a38aad Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 00:41:55 +1000 Subject: [PATCH 10/85] Update aws_lambda_powertools/event_handler/api_gateway.py Co-authored-by: Heitor Lessa Signed-off-by: walmsles <2704782+walmsles@users.noreply.github.com> --- aws_lambda_powertools/event_handler/api_gateway.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 68ae1b304ef..72e7688af73 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -370,7 +370,7 @@ def get( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middleware: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable]] = None, ): """Get route decorator with GET `method` From e765ebcf755cf94f247e54924d0b64233f476d3b Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 00:46:47 +1000 Subject: [PATCH 11/85] Apply suggestions from code review fix(middleware-intent): rename middleware to middlewares Co-authored-by: Heitor Lessa Signed-off-by: walmsles <2704782+walmsles@users.noreply.github.com> --- .../event_handler/api_gateway.py | 28 +++++++++---------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 72e7688af73..70d5a1d9256 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -394,7 +394,7 @@ def lambda_handler(event, context): return app.resolve(event, context) ``` """ - return self.route(rule, "GET", cors, compress, cache_control, middleware) + return self.route(rule, "GET", cors, compress, cache_control, middlewares) def post( self, @@ -402,7 +402,7 @@ def post( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middleware: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable]] = None, ): """Post route decorator with POST `method` @@ -427,7 +427,7 @@ def lambda_handler(event, context): return app.resolve(event, context) ``` """ - return self.route(rule, "POST", cors, compress, cache_control, middleware) + return self.route(rule, "POST", cors, compress, cache_control, middlewares) def put( self, @@ -435,7 +435,7 @@ def put( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middleware: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable]] = None, ): """Put route decorator with PUT `method` @@ -460,7 +460,7 @@ def lambda_handler(event, context): return app.resolve(event, context) ``` """ - return self.route(rule, "PUT", cors, compress, cache_control, middleware) + return self.route(rule, "PUT", cors, compress, cache_control, middlewares) def delete( self, @@ -468,7 +468,7 @@ def delete( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middleware: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable]] = None, ): """Delete route decorator with DELETE `method` @@ -492,7 +492,7 @@ def lambda_handler(event, context): return app.resolve(event, context) ``` """ - return self.route(rule, "DELETE", cors, compress, cache_control, middleware) + return self.route(rule, "DELETE", cors, compress, cache_control, middlewares) def patch( self, @@ -500,7 +500,7 @@ def patch( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middleware: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable]] = None, ): """Patch route decorator with PATCH `method` @@ -527,7 +527,7 @@ def lambda_handler(event, context): return app.resolve(event, context) ``` """ - return self.route(rule, "PATCH", cors, compress, cache_control, middleware) + return self.route(rule, "PATCH", cors, compress, cache_control, middlewares) def append_context(self, **additional_context): """Append key=value data as routing context""" @@ -629,7 +629,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middleware: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable]] = None, ): """Route decorator includes parameter `method`""" @@ -642,7 +642,7 @@ def register_resolver(func: Callable): cors_enabled = cors for item in methods: - _route = Route(item, self._compile_regex(rule), func, cors_enabled, compress, cache_control, middleware) + _route = Route(item, self._compile_regex(rule), func, cors_enabled, compress, cache_control, middlewares) # The more specific route wins. # We store dynamic (/studies/{studyid}) and static routes (/studies/fetch) separately. @@ -838,7 +838,7 @@ def _call_route(self, route: Route, args: Dict[str, str]) -> ResponseBuilder: """Actually call the matching route with any provided keyword arguments.""" try: return ResponseBuilder( - self._to_response(route(router_middleware=self.router_middleware, app=self, args=args)), + self._to_response(route(router_middleware=self.router_middlewares, app=self, args=args)), route, ) except Exception as exc: @@ -978,13 +978,13 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middleware: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable]] = None, ): def register_route(func: Callable): # Convert methods to tuple. It needs to be hashable as its part of the self._routes dict key methods = (method,) if isinstance(method, str) else tuple(method) - tuple_key = (rule, methods, cors, compress, cache_control) + route_key = (rule, methods, cors, compress, cache_control) # Collate Middleware for routes if middleware is not None: From 6e542566ae0e564795cc8bf76758caeb0c1e25be Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 00:56:40 +1000 Subject: [PATCH 12/85] fix(naming-intent): rename middleware to middlewares universally in all contexts --- .../event_handler/api_gateway.py | 42 +++++++++++-------- .../event_handler/test_api_gateway.py | 10 ++--- 2 files changed, 30 insertions(+), 22 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 70d5a1d9256..14e3754341a 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -231,7 +231,7 @@ def __init__( self.cache_control = cache_control self.middlewares = middlewares or [] - def __call__(self, router_middleware: List[Callable], app, args: Dict[str, str]): + def __call__(self, router_middlewares: List[Callable], app, args: Dict[str, str]): """Builds the middleware stack using global and route middlewares, redefining the original handler function""" if not self._middleware_built: # prepend global router middleware first @@ -239,9 +239,9 @@ def __call__(self, router_middleware: List[Callable], app, args: Dict[str, str]) # IMPORTANT: # this must be the last mdidleware in the stack to avoid breaking changes # for the registered API call signature (Maintain Backward Compatibility) - all_middleware.append(registered_api_middleware) + all_middlewares.append(registered_api_middleware) - for handler in reversed(all_middleware): + for handler in reversed(all_middlewares): self.func = MiddlewareHandler(handler=handler, next_handler=self.func) self._middleware_built = True @@ -358,11 +358,11 @@ def route( ): raise NotImplementedError() - def use(self, middleware: Union[Callable, List[Callable]]): + def use(self, middlewares: Union[Callable, List[Callable]]): """Add a middleware to the router""" - if not isinstance(middleware, list): - middleware = [middleware] - self.router_middleware = list(self.router_middleware) + list(middleware) + if not isinstance(middlewares, list): + middlewares = [middlewares] + self.router_middlewares = self.router_middlewares + middlewares def get( self, @@ -642,7 +642,15 @@ def register_resolver(func: Callable): cors_enabled = cors for item in methods: - _route = Route(item, self._compile_regex(rule), func, cors_enabled, compress, cache_control, middlewares) + _route = Route( + item, + self._compile_regex(rule), + func, + cors_enabled, + compress, + cache_control, + middlewares, + ) # The more specific route wins. # We store dynamic (/studies/{studyid}) and static routes (/studies/fetch) separately. @@ -838,7 +846,7 @@ def _call_route(self, route: Route, args: Dict[str, str]) -> ResponseBuilder: """Actually call the matching route with any provided keyword arguments.""" try: return ResponseBuilder( - self._to_response(route(router_middleware=self.router_middlewares, app=self, args=args)), + self._to_response(route(router_middlewares=self.router_middlewares, app=self, args=args)), route, ) except Exception as exc: @@ -987,16 +995,16 @@ def register_route(func: Callable): route_key = (rule, methods, cors, compress, cache_control) # Collate Middleware for routes - if middleware is not None: - for handler in middleware: - if self._routes_with_middleware.get(tuple_key) is None: - self._routes_with_middleware[tuple_key] = [handler] + if middlewares is not None: + for handler in middlewares: + if self._routes_with_middleware.get(route_key) is None: + self._routes_with_middleware[route_key] = [handler] else: - self._routes_with_middleware[tuple_key].append(handler) + self._routes_with_middleware[route_key].append(handler) else: - self._routes_with_middleware[tuple_key] = [] + self._routes_with_middleware[route_key] = [] - self._routes[tuple_key] = func + self._routes[route_key] = func return func @@ -1024,7 +1032,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middleware: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable]] = None, ): # NOTE: see #1552 for more context. return super().route(rule.rstrip("/"), method, cors, compress, cache_control) diff --git a/tests/functional/event_handler/test_api_gateway.py b/tests/functional/event_handler/test_api_gateway.py index 66d1f9124ad..95038402e6f 100644 --- a/tests/functional/event_handler/test_api_gateway.py +++ b/tests/functional/event_handler/test_api_gateway.py @@ -1771,7 +1771,7 @@ def middleware_2(app, get_response, **kwargs): return response - @app.get("/my/path", middleware=[middleware_1, middleware_2]) + @app.get("/my/path", middlewares=[middleware_1, middleware_2]) def get_lambda(another_one: int, custom: str) -> Response: assert isinstance(app.current_event, APIGatewayProxyEvent) assert another_one == 6 @@ -1835,7 +1835,7 @@ def middleware_one(app, get_response, **kwargs): return response - @app.get("//", middleware=[middleware_one]) + @app.get("//", middlewares=[middleware_one]) def get_lambda(my_id: str, name: str, injected: str) -> Response: assert name == "my" assert injected == "injected_value" @@ -1856,7 +1856,7 @@ def test_route_cors_middleware(): # AND http method set to GET app = ApiGatewayResolver() - @app.get("/my/path", middleware=[CORSMiddleware()]) + @app.get("/my/path", middlewares=[CORSMiddleware()]) def with_cors() -> Response: return Response(200, content_types.TEXT_HTML, "test") @@ -1922,7 +1922,7 @@ def test_cache_control_middleware_200(): # GIVEN a function with cache_control set app = ApiGatewayResolver() - @app.get("/success", middleware=[CacheControlMiddleware("max-age=600")]) + @app.get("/success", middlewares=[CacheControlMiddleware("max-age=600")]) def with_cache_control() -> Response: return Response(200, content_types.TEXT_HTML, "has 200 response") @@ -1943,7 +1943,7 @@ def test_cache_control_middleware_non_200(): # GIVEN a function with cache_control set app = ApiGatewayResolver() - @app.delete("/fails", middleware=[CacheControlMiddleware("max-age=600")]) + @app.delete("/fails", middlewares=[CacheControlMiddleware("max-age=600")]) def with_cache_control_has_500() -> Response: return Response(503, content_types.TEXT_HTML, "has 503 response") From 727effbd3faf2068608727f6a277221c05742c43 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 01:16:41 +1000 Subject: [PATCH 13/85] fix(args-debt): rename args to route_arguments in all places --- aws_lambda_powertools/event_handler/api_gateway.py | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 14e3754341a..c4a63b49c42 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -231,7 +231,7 @@ def __init__( self.cache_control = cache_control self.middlewares = middlewares or [] - def __call__(self, router_middlewares: List[Callable], app, args: Dict[str, str]): + def __call__(self, router_middlewares: List[Callable], app, route_arguments: Dict[str, str]): """Builds the middleware stack using global and route middlewares, redefining the original handler function""" if not self._middleware_built: # prepend global router middleware first @@ -246,7 +246,7 @@ def __call__(self, router_middlewares: List[Callable], app, args: Dict[str, str] self._middleware_built = True - return self.func(app, **args) + return self.func(app, **route_arguments) class ResponseBuilder: @@ -842,11 +842,13 @@ def _not_found(self, method: str) -> ResponseBuilder: ), ) - def _call_route(self, route: Route, args: Dict[str, str]) -> ResponseBuilder: + def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> ResponseBuilder: """Actually call the matching route with any provided keyword arguments.""" try: return ResponseBuilder( - self._to_response(route(router_middlewares=self.router_middlewares, app=self, args=args)), + self._to_response( + route(router_middlewares=self.router_middlewares, app=self, route_arguments=route_arguments), + ), route, ) except Exception as exc: From 0afe31ca8c7f6add35363a2887c62f3255522266 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 11:06:33 +1000 Subject: [PATCH 14/85] fix(middleware-clarity): Rename and repackage middleware construction with more documentation and clearer naming conventions around intent. Renamed MiddlewareHandler to MiddlewareWrapper since this is what it does and introdcued a base.py with MiddlewareHandler abstract class with documentation to guide developers better, rename middleware to middlewares everywhere. --- .../event_handler/api_gateway.py | 123 +++++++++++++++--- .../{middleware => middlewares}/__init__.py | 0 .../event_handler/middlewares/base.py | 66 ++++++++++ .../cache_control.py | 7 +- .../{middleware => middlewares}/cors.py | 7 +- .../registered_api.py | 9 +- .../event_handler/test_api_gateway.py | 4 +- 7 files changed, 187 insertions(+), 29 deletions(-) rename aws_lambda_powertools/event_handler/{middleware => middlewares}/__init__.py (100%) create mode 100644 aws_lambda_powertools/event_handler/middlewares/base.py rename aws_lambda_powertools/event_handler/{middleware => middlewares}/cache_control.py (74%) rename aws_lambda_powertools/event_handler/{middleware => middlewares}/cors.py (76%) rename aws_lambda_powertools/event_handler/{middleware => middlewares}/registered_api.py (60%) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index c4a63b49c42..68025fa5357 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -25,7 +25,7 @@ from aws_lambda_powertools.event_handler import content_types from aws_lambda_powertools.event_handler.exceptions import NotFoundError, ServiceError -from aws_lambda_powertools.event_handler.middleware.registered_api import registered_api_middleware +from aws_lambda_powertools.event_handler.middlewares.registered_api import registered_api_adapter from aws_lambda_powertools.shared.cookies import Cookie from aws_lambda_powertools.shared.functions import powertools_dev_is_set from aws_lambda_powertools.shared.json_encoder import Encoder @@ -211,8 +211,6 @@ def __init__( class Route: """Internally used Route Configuration""" - _middleware_built = False - def __init__( self, method: str, @@ -231,23 +229,82 @@ def __init__( self.cache_control = cache_control self.middlewares = middlewares or [] - def __call__(self, router_middlewares: List[Callable], app, route_arguments: Dict[str, str]): - """Builds the middleware stack using global and route middlewares, redefining the original handler function""" - if not self._middleware_built: - # prepend global router middleware first - all_middlewares = router_middlewares + self.middlewares + self.middleware_stack_built = False - # IMPORTANT: # this must be the last mdidleware in the stack to avoid breaking changes - # for the registered API call signature (Maintain Backward Compatibility) - all_middlewares.append(registered_api_middleware) + def __call__( + self, + router_middlewares: List[Callable], + app, + route_arguments: Dict[str, str], + ) -> Union[Dict, Tuple, Response]: + """Calling the Router class instance will trigger the following actions: + 1. If Route Middleware execution stack has not been built, build it + 2. Execute the Route Middleware execution stack wrapping the original function + handler with the app and route arguments. - for handler in reversed(all_middlewares): - self.func = MiddlewareHandler(handler=handler, next_handler=self.func) + Parameters + ---------- + router_middlewares: List[Callable] + The list of Router Middlewares (assigned to ALL routes) + app: Callable + The ApiGatewayResolver instance to pass into the middleware execution stack + route_arguments: Dict[str, str] + The route arguments to pass to the app function (extracted from the Api Gateway + Lambda Message structure from AWS) - self._middleware_built = True + Returns + ------- + Union[Dict, Tuple, Response] + Returns an API Response object in ALL cases, excepting when the original API route + handler is executed which may also return a Dict or Tuple response. + """ + if not self.middleware_stack_built: + self.build_middleware_stack(router_middlewares=router_middlewares) return self.func(app, **route_arguments) + def build_middleware_stack(self, router_middlewares: List[Callable]) -> None: + """ + Builds the middleware execution stack for the handler by wrapping each + handler in an instance of MiddlewareWrapper which is used to contain the state + of each middleware step. + + Middleware is represented by a standard Python Callable construct. Any Middleware + handler wanting to short-circuit the middlware call chain should raise an execution + to force the Python call stack created by the handler call-chain to naturally un-wind. + + This becomes a simple concept for Users ot understand and reason with - no additional + gymanstics other than plain old try ... except. + + Notes + ----- + The Route Middleware execution stack is executed in reverse order. This is so the stack of + middleware handlers is applied in the order of being added to the handler. + """ + all_middlewares = router_middlewares + self.middlewares + + # IMPORTANT: + # 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 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 + all_middlewares.append(registered_api_adapter) + + # Wrap the original route handler function in the middleware handlers + # using the MiddlewareWrapper class callable construct in reverse order to + # ensure middleware is applied in the order the user defined. + # + # Start with the route function and wrap from last to the first Middleware handler. + for handler in reversed(all_middlewares): + self.func = MiddlewareStackWrapper(handler=handler, get_response=self.func) + + self.middleware_stack_built = True + class ResponseBuilder: """Internally used Response builder""" @@ -538,19 +595,43 @@ def clear_context(self): self.context.clear() -class MiddlewareHandler: - """Represents a callable Middleware function used to build a middleware stack when a route is resolved""" +class MiddlewareStackWrapper: + """ + MiddlewareStackWrapper + --------------------- + + This class is the core Middle wrapper that contains the context of each middleware + frame in the constructed middlewar call-stack. + """ def __init__( self, - handler: Callable[..., Any], - next_handler: Callable[..., Any], + handler: Callable, + get_response: Callable, ) -> None: - self.handler: Callable[..., Any] = handler - self.next_handler: Callable[..., Any] = next_handler + self.handler: Callable = handler + self.get_response: Callable = get_response def __call__(self, app: BaseRouter, **kwargs) -> Any: - return self.handler(app, self.next_handler, **kwargs) + """ + Call the middleware stack wrapper + + Parameters + ---------- + app: BaseRouter + The router instance + **kwargs + Any additional arguments to pass to the middleware stack wrapper + + Returns + ------- + Any + (tech-debt for backward compatability). The resposne type should be a + Resposne object in all cases excepting when the oiginal API rout handler + is executed which will return one of 3 outputs. + + """ + return self.handler(app, self.get_response, **kwargs) class ApiGatewayResolver(BaseRouter): diff --git a/aws_lambda_powertools/event_handler/middleware/__init__.py b/aws_lambda_powertools/event_handler/middlewares/__init__.py similarity index 100% rename from aws_lambda_powertools/event_handler/middleware/__init__.py rename to aws_lambda_powertools/event_handler/middlewares/__init__.py diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py new file mode 100644 index 00000000000..7d0cebb6224 --- /dev/null +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -0,0 +1,66 @@ +from abc import ABC, abstractmethod +from typing import Callable + +from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response + + +class BaseMiddlewareHandler(ABC): + """ + Base class for Middleware Handlers + + 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`. + + + ```python + + # Place code here for actions BEFORE the next middleware handler is called + # or optionally raise an excpetion 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) + + # Place code ehre 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` + block - you can also catch specific types of errors this way so your middleware only handles + specific types of exceptions. + + for example: + ============ + + ```python + + try: + result: Response = get_response(app, my_custom_arg="handled", **kwargs) + except MyCustomValidationException as e: + # Make sure we send back a 400 resposne for any Custom Validation Exceptions. + result.status_code = 400 + result.body = {"message": str(e)} + + return result + ``` + + :param app: The ApiGatewayResolver object + :param get_response: The next middleware handler in the chain + :param kwargs: Any additional arguments to pass to the next middleware handler + :return: The response from the next middleware handler in the chain + + """ + + @abstractmethod + def __call__(self, app: ApiGatewayResolver, get_response: Callable, **kwargs) -> Response: + """ + The Middleware handler function. + + :param app: The ApiGatewayResolver object + :param get_response: The next middleware handler in the chain + :param kwargs: Any additional arguments to pass to the next middleware handler + :return: The response from the next middleware handler in the chain + """ + raise NotImplementedError() diff --git a/aws_lambda_powertools/event_handler/middleware/cache_control.py b/aws_lambda_powertools/event_handler/middlewares/cache_control.py similarity index 74% rename from aws_lambda_powertools/event_handler/middleware/cache_control.py rename to aws_lambda_powertools/event_handler/middlewares/cache_control.py index c2e323e826c..e23f4fa1fcf 100644 --- a/aws_lambda_powertools/event_handler/middleware/cache_control.py +++ b/aws_lambda_powertools/event_handler/middlewares/cache_control.py @@ -1,9 +1,14 @@ from typing import Callable, Optional from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response +from aws_lambda_powertools.event_handler.middlewares.base import BaseMiddlewareHandler -class CacheControlMiddleware: +class CacheControlMiddleware(BaseMiddlewareHandler): + """ + CacheControlMiddleware adds Cache-Control header to responses with status code 200. + """ + def __init__(self, cache_control: Optional[str] = None): self.cache_control = cache_control diff --git a/aws_lambda_powertools/event_handler/middleware/cors.py b/aws_lambda_powertools/event_handler/middlewares/cors.py similarity index 76% rename from aws_lambda_powertools/event_handler/middleware/cors.py rename to aws_lambda_powertools/event_handler/middlewares/cors.py index e687f572004..d7089bafa5b 100644 --- a/aws_lambda_powertools/event_handler/middleware/cors.py +++ b/aws_lambda_powertools/event_handler/middlewares/cors.py @@ -1,9 +1,14 @@ from typing import Callable, Optional from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, CORSConfig, Response +from aws_lambda_powertools.event_handler.middlewares.base import BaseMiddlewareHandler -class CORSMiddleware: +class CORSMiddleware(BaseMiddlewareHandler): + """ + CORSMiddleware adds CORS headers to the response. + """ + def __init__(self, config: Optional[CORSConfig] = None): self.cors = config or CORSConfig() diff --git a/aws_lambda_powertools/event_handler/middleware/registered_api.py b/aws_lambda_powertools/event_handler/middlewares/registered_api.py similarity index 60% rename from aws_lambda_powertools/event_handler/middleware/registered_api.py rename to aws_lambda_powertools/event_handler/middlewares/registered_api.py index 0e292259dfa..28b15f45088 100644 --- a/aws_lambda_powertools/event_handler/middleware/registered_api.py +++ b/aws_lambda_powertools/event_handler/middlewares/registered_api.py @@ -1,13 +1,14 @@ import logging -from typing import Callable +from typing import Any, Callable logger = logging.getLogger(__name__) # Note: Type hinting not available due to cyclic dependency between api_gateway.py and this module -def registered_api_middleware(app, get_response: Callable, **kwargs): +def registered_api_adapter(app, get_response: Callable, **kwargs) -> Any: """ - Call the registered API using the **kwargs provided. + Calls the registered API using ONLY the **kwargs provided to ensure the + call signature of existing defined router of Users does not create a breaking change. :param app: The API Gateway resolver :param get_response: The function to handle the API @@ -15,6 +16,6 @@ def registered_api_middleware(app, get_response: Callable, **kwargs): :return: The API Response Object This middleware enables backward compatibility for the existing API routes model in Powertools - and it MUST be the final middleware in the middleware stack. + and it MUST BE THE LAST middleware in the middleware stack. """ return app._to_response(get_response(**kwargs)) diff --git a/tests/functional/event_handler/test_api_gateway.py b/tests/functional/event_handler/test_api_gateway.py index 95038402e6f..eafaab10f41 100644 --- a/tests/functional/event_handler/test_api_gateway.py +++ b/tests/functional/event_handler/test_api_gateway.py @@ -30,8 +30,8 @@ ServiceError, UnauthorizedError, ) -from aws_lambda_powertools.event_handler.middleware.cache_control import CacheControlMiddleware -from aws_lambda_powertools.event_handler.middleware.cors import CORSMiddleware +from aws_lambda_powertools.event_handler.middlewares.cache_control import CacheControlMiddleware +from aws_lambda_powertools.event_handler.middlewares.cors import CORSMiddleware from aws_lambda_powertools.shared import constants from aws_lambda_powertools.shared.cookies import Cookie from aws_lambda_powertools.shared.json_encoder import Encoder From 8501b9afb4f4432c16b5adff847250e950bc20ad Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 11:35:19 +1000 Subject: [PATCH 15/85] fix(jsdocs): added docs to MiddlewareStackWrapper and BaseMiddlewareHandler classes. --- .../event_handler/api_gateway.py | 32 +++++++++++++------ .../event_handler/middlewares/base.py | 20 ++++++++++++ 2 files changed, 43 insertions(+), 9 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 68025fa5357..653fe6e4332 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -301,7 +301,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.func = MiddlewareStackWrapper(handler=handler, get_response=self.func) + self.func = MiddlewareStackWrapper(handler=handler, next_middleware=self.func) self.middleware_stack_built = True @@ -597,20 +597,34 @@ def clear_context(self): class MiddlewareStackWrapper: """ - MiddlewareStackWrapper - --------------------- - - This class is the core Middle wrapper that contains the context of each middleware - frame in the constructed middlewar call-stack. + creates a Middle Stack Wrapper instance to be used as a "Frame" in the overall stack of + middleware functions. Each instance contains the current middleware to be executed and the next + middleware function to be called in the stack. + + In this way the middleware stack is constructed in a recursive fashion, with each middleware + calling the next as a simple function call. The actual Python call-stack will contain + each MiddlewareStackWrapper "Frame", meaning any Middleware function can cause the + entire Middleware call chain to be exited early (short-circuited) by raising an exception + or by simply returning early with a custom Response. The decision to short-circuit the middleware + chain is at the user's discretion but instantly available due to the Wrapped nature of the + callable constructs in the Middleware stack and each Middleware function having complete control over + whether the "Next" handler in the stack is called or not. + + Parameters + ---------- + handler : Callable + The API route handler to be invoked when this class is executed. + next_middleware : Callable + The next middleware in the middleware stack. """ def __init__( self, handler: Callable, - get_response: Callable, + next_middleware: Callable, ) -> None: self.handler: Callable = handler - self.get_response: Callable = get_response + self.next_middleware: Callable = next_middleware def __call__(self, app: BaseRouter, **kwargs) -> Any: """ @@ -631,7 +645,7 @@ def __call__(self, app: BaseRouter, **kwargs) -> Any: is executed which will return one of 3 outputs. """ - return self.handler(app, self.get_response, **kwargs) + return self.handler(app, self.next_middleware, **kwargs) class ApiGatewayResolver(BaseRouter): diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index 7d0cebb6224..5ba0771edaf 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -46,6 +46,26 @@ class BaseMiddlewareHandler(ABC): return result ``` + 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` + handler to get the response from the next middleware handler in the chain. + + for example: + ============ + If you wanted to ensure API callers cannot call a DELETE verb on your API (regardless of defined routes) + you could do so with the following middleware implementation. + + ```python + # If invalid http_method is used - return a 405 error + # and return early to short-circuit the middleware execution chain + if app.current_event.http_method == "DELETE": + return Response(status_code=405, body={"message": "DELETE verb not allowed"}) + + + # Call the next middleware in the chain (needed for when condition above is valid) + return get_response(app, **kwargs) + + :param app: The ApiGatewayResolver object :param get_response: The next middleware handler in the chain :param kwargs: Any additional arguments to pass to the next middleware handler From 0d59e12f72a56cf86e546f7a2eb8cbb96b0b9feb Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 4 Aug 2023 12:05:14 +1000 Subject: [PATCH 16/85] fix(types): Mkae MiddlewareStackWrapper __call__ return type more specific than ANY. --- aws_lambda_powertools/event_handler/api_gateway.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 653fe6e4332..164d3c7cb77 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -626,7 +626,7 @@ def __init__( self.handler: Callable = handler self.next_middleware: Callable = next_middleware - def __call__(self, app: BaseRouter, **kwargs) -> Any: + def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]: """ Call the middleware stack wrapper @@ -639,9 +639,9 @@ def __call__(self, app: BaseRouter, **kwargs) -> Any: Returns ------- - Any - (tech-debt for backward compatability). The resposne type should be a - Resposne object in all cases excepting when the oiginal API rout handler + Union[Dict, Tuple, Response] + (tech-debt for backward compatability). The response type should be a + Response object in all cases excepting when the oiginal API rout handler is executed which will return one of 3 outputs. """ From 6b9b36912abe0cec4721774ff099731c499d8141 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Sat, 5 Aug 2023 15:35:16 +1000 Subject: [PATCH 17/85] fix(middlewares): internalise registered_api_adapter and remove Cors/Cache middleware (these 2 not required) --- .../event_handler/api_gateway.py | 18 ++- .../middlewares/cache_control.py | 25 ---- .../event_handler/middlewares/cors.py | 24 ---- .../middlewares/registered_api.py | 21 ---- .../event_handler/test_api_gateway.py | 111 ------------------ 5 files changed, 17 insertions(+), 182 deletions(-) delete mode 100644 aws_lambda_powertools/event_handler/middlewares/cache_control.py delete mode 100644 aws_lambda_powertools/event_handler/middlewares/cors.py delete mode 100644 aws_lambda_powertools/event_handler/middlewares/registered_api.py diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 164d3c7cb77..9863929cc18 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -25,7 +25,6 @@ from aws_lambda_powertools.event_handler import content_types from aws_lambda_powertools.event_handler.exceptions import NotFoundError, ServiceError -from aws_lambda_powertools.event_handler.middlewares.registered_api import registered_api_adapter from aws_lambda_powertools.shared.cookies import Cookie from aws_lambda_powertools.shared.functions import powertools_dev_is_set from aws_lambda_powertools.shared.json_encoder import Encoder @@ -648,6 +647,23 @@ def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]: return self.handler(app, self.next_middleware, **kwargs) +# No type checking possible due to Dependency order of definition () +def registered_api_adapter(app, get_response: Callable, **kwargs) -> Union[Dict, Tuple, Response]: + """ + Calls the registered API using ONLY the **kwargs provided to ensure the + call signature of existing defined router of Users does not create a breaking change. + + :param app: The API Gateway resolver + :param get_response: The function to handle the API + :param kwargs: The arguments to pass to the API + :return: The API Response Object + + This middleware enables backward compatibility for the existing API routes model in Powertools + and it MUST BE THE LAST middleware in the middleware stack. + """ + return app._to_response(get_response(**kwargs)) + + class ApiGatewayResolver(BaseRouter): """API Gateway and ALB proxy resolver diff --git a/aws_lambda_powertools/event_handler/middlewares/cache_control.py b/aws_lambda_powertools/event_handler/middlewares/cache_control.py deleted file mode 100644 index e23f4fa1fcf..00000000000 --- a/aws_lambda_powertools/event_handler/middlewares/cache_control.py +++ /dev/null @@ -1,25 +0,0 @@ -from typing import Callable, Optional - -from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response -from aws_lambda_powertools.event_handler.middlewares.base import BaseMiddlewareHandler - - -class CacheControlMiddleware(BaseMiddlewareHandler): - """ - CacheControlMiddleware adds Cache-Control header to responses with status code 200. - """ - - def __init__(self, cache_control: Optional[str] = None): - self.cache_control = cache_control - - def __call__(self, app: ApiGatewayResolver, get_response: Callable, **kwargs) -> Response: - # Modify request details here before calling handler - - # Call Handler and get response - result: Response = get_response(app, **kwargs) - - # Modify Response from Handler here before returning - cache_control = self.cache_control if result.status_code == 200 else "no-cache" - result.headers["Cache-Control"] = cache_control or "" - - return result diff --git a/aws_lambda_powertools/event_handler/middlewares/cors.py b/aws_lambda_powertools/event_handler/middlewares/cors.py deleted file mode 100644 index d7089bafa5b..00000000000 --- a/aws_lambda_powertools/event_handler/middlewares/cors.py +++ /dev/null @@ -1,24 +0,0 @@ -from typing import Callable, Optional - -from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, CORSConfig, Response -from aws_lambda_powertools.event_handler.middlewares.base import BaseMiddlewareHandler - - -class CORSMiddleware(BaseMiddlewareHandler): - """ - CORSMiddleware adds CORS headers to the response. - """ - - def __init__(self, config: Optional[CORSConfig] = None): - self.cors = config or CORSConfig() - - def __call__(self, app: ApiGatewayResolver, get_response: Callable, **kwargs) -> Response: - # Modify request details here before calling handler - - # Call Handler and get response - result: Response = get_response(app, **kwargs) - - # Modify Response from Handler here before returning - result.headers.update(self.cors.to_dict(app.current_event.get_header_value("Origin"))) - - return result diff --git a/aws_lambda_powertools/event_handler/middlewares/registered_api.py b/aws_lambda_powertools/event_handler/middlewares/registered_api.py deleted file mode 100644 index 28b15f45088..00000000000 --- a/aws_lambda_powertools/event_handler/middlewares/registered_api.py +++ /dev/null @@ -1,21 +0,0 @@ -import logging -from typing import Any, Callable - -logger = logging.getLogger(__name__) - - -# Note: Type hinting not available due to cyclic dependency between api_gateway.py and this module -def registered_api_adapter(app, get_response: Callable, **kwargs) -> Any: - """ - Calls the registered API using ONLY the **kwargs provided to ensure the - call signature of existing defined router of Users does not create a breaking change. - - :param app: The API Gateway resolver - :param get_response: The function to handle the API - :param kwargs: The arguments to pass to the API - :return: The API Response Object - - This middleware enables backward compatibility for the existing API routes model in Powertools - and it MUST BE THE LAST middleware in the middleware stack. - """ - return app._to_response(get_response(**kwargs)) diff --git a/tests/functional/event_handler/test_api_gateway.py b/tests/functional/event_handler/test_api_gateway.py index eafaab10f41..8a659383c40 100644 --- a/tests/functional/event_handler/test_api_gateway.py +++ b/tests/functional/event_handler/test_api_gateway.py @@ -30,8 +30,6 @@ ServiceError, UnauthorizedError, ) -from aws_lambda_powertools.event_handler.middlewares.cache_control import CacheControlMiddleware -from aws_lambda_powertools.event_handler.middlewares.cors import CORSMiddleware from aws_lambda_powertools.shared import constants from aws_lambda_powertools.shared.cookies import Cookie from aws_lambda_powertools.shared.json_encoder import Encoder @@ -1849,112 +1847,3 @@ def get_lambda(my_id: str, name: str, injected: str) -> Response: assert result["statusCode"] == 200 assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] assert result["body"] == "path" - - -def test_route_cors_middleware(): - # GIVEN a function with cors middleware (class definition) - # AND http method set to GET - app = ApiGatewayResolver() - - @app.get("/my/path", middlewares=[CORSMiddleware()]) - def with_cors() -> Response: - return Response(200, content_types.TEXT_HTML, "test") - - @app.get("/without-cors") - def without_cors() -> Response: - return Response(200, content_types.TEXT_HTML, "test") - - def handler(event, context): - return app.resolve(event, context) - - # WHEN calling the event handler - result = handler(LOAD_GW_EVENT, None) - - # THEN the headers should include cors headers - assert "multiValueHeaders" in result - headers = result["multiValueHeaders"] - assert headers["Content-Type"] == [content_types.TEXT_HTML] - assert headers["Access-Control-Allow-Origin"] == ["https://aws.amazon.com"] - assert "Access-Control-Allow-Credentials" not in headers - assert headers["Access-Control-Allow-Headers"] == [",".join(sorted(CORSConfig._REQUIRED_HEADERS))] - - # THEN for routes without cors flag return no cors headers - mock_event = {"path": "/without-cors", "httpMethod": "GET"} - result = handler(mock_event, None) - assert "Access-Control-Allow-Origin" not in result["multiValueHeaders"] - - -def test_router_cors_middleware(): - # GIVEN a function with cors middleware (class definition) - # AND http method set to GET - app = ApiGatewayResolver() - app.use(CORSMiddleware()) - - @app.get("/my/path") - def with_cors() -> Response: - return Response(200, content_types.TEXT_HTML, "test") - - @app.get("/without-cors") - def without_cors() -> Response: - return Response(200, content_types.TEXT_HTML, "test") - - def handler(event, context): - return app.resolve(event, context) - - # WHEN calling the event handler - result = handler(LOAD_GW_EVENT, None) - - # THEN the headers should include cors headers - assert "multiValueHeaders" in result - headers = result["multiValueHeaders"] - assert headers["Content-Type"] == [content_types.TEXT_HTML] - assert headers["Access-Control-Allow-Origin"] == ["https://aws.amazon.com"] - assert "Access-Control-Allow-Credentials" not in headers - assert headers["Access-Control-Allow-Headers"] == [",".join(sorted(CORSConfig._REQUIRED_HEADERS))] - - # THEN for routes without cors flag return no cors headers - mock_event = {"path": "/my/request", "httpMethod": "GET"} - result = handler(mock_event, None) - assert "Access-Control-Allow-Origin" not in result["multiValueHeaders"] - - -def test_cache_control_middleware_200(): - # GIVEN a function with cache_control set - app = ApiGatewayResolver() - - @app.get("/success", middlewares=[CacheControlMiddleware("max-age=600")]) - def with_cache_control() -> Response: - return Response(200, content_types.TEXT_HTML, "has 200 response") - - def handler(event, context): - return app.resolve(event, context) - - # WHEN calling the event handler - # AND the function returns a 200 status code - result = handler({"path": "/success", "httpMethod": "GET"}, None) - - # THEN return the set Cache-Control - headers = result["multiValueHeaders"] - assert headers["Content-Type"] == [content_types.TEXT_HTML] - assert headers["Cache-Control"] == ["max-age=600"] - - -def test_cache_control_middleware_non_200(): - # GIVEN a function with cache_control set - app = ApiGatewayResolver() - - @app.delete("/fails", middlewares=[CacheControlMiddleware("max-age=600")]) - def with_cache_control_has_500() -> Response: - return Response(503, content_types.TEXT_HTML, "has 503 response") - - def handler(event, context): - return app.resolve(event, context) - - # WHEN calling the event handler - # AND the function returns a 503 status code - result = handler({"path": "/fails", "httpMethod": "DELETE"}, None) - - # THEN return a Cache-Control of "no-cache" - headers = result["multiValueHeaders"] - assert headers["Content-Type"] == [content_types.TEXT_HTML] - assert headers["Cache-Control"] == ["no-cache"] From 409da32436e1497697536e0e34f401e8d9374fb4 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Sat, 5 Aug 2023 18:01:21 +1000 Subject: [PATCH 18/85] feat(middlewares): Add chema validation middleware and internalise registered_api_adapter, type fix BaseMiddlewarehandler --- .../event_handler/api_gateway.py | 31 +++---- .../event_handler/middlewares/__init__.py | 5 +- .../event_handler/middlewares/base.py | 13 ++- .../middlewares/schema_validation.py | 59 ++++++++++++++ ...pigatewayeSchemaMiddlwareInvalidEvent.json | 81 +++++++++++++++++++ .../apigatewayeSchemaMiddlwareValidEvent.json | 81 +++++++++++++++++++ tests/functional/event_handler/conftest.py | 32 ++++++++ .../event_handler/test_api_gateway.py | 31 +++++++ .../event_handler/test_api_middlewares.py | 63 +++++++++++++++ 9 files changed, 378 insertions(+), 18 deletions(-) create mode 100644 aws_lambda_powertools/event_handler/middlewares/schema_validation.py create mode 100644 tests/events/apigatewayeSchemaMiddlwareInvalidEvent.json create mode 100644 tests/events/apigatewayeSchemaMiddlwareValidEvent.json create mode 100644 tests/functional/event_handler/test_api_middlewares.py diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 9863929cc18..d8f096e91ac 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -218,7 +218,7 @@ def __init__( cors: bool, compress: bool, cache_control: Optional[str], - middlewares: Optional[List[Callable]], + middlewares: Optional[List[Callable[..., Any]]], ): self.method = method.upper() self.rule = rule @@ -410,14 +410,17 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): raise NotImplementedError() - def use(self, middlewares: Union[Callable, List[Callable]]): - """Add a middleware to the router""" - if not isinstance(middlewares, list): - middlewares = [middlewares] + def use(self, middlewares: List[Callable[..., Any]]): + """ + Add a List of middlewares to the global routetr middleware list + + These Middleware handlers will be executed in order of adding to the array and will + be executed before any specific middleware applied at the actual route level. + """ self.router_middlewares = self.router_middlewares + middlewares def get( @@ -426,7 +429,7 @@ def get( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): """Get route decorator with GET `method` @@ -458,7 +461,7 @@ def post( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): """Post route decorator with POST `method` @@ -491,7 +494,7 @@ def put( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): """Put route decorator with PUT `method` @@ -524,7 +527,7 @@ def delete( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): """Delete route decorator with DELETE `method` @@ -648,7 +651,7 @@ def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]: # No type checking possible due to Dependency order of definition () -def registered_api_adapter(app, get_response: Callable, **kwargs) -> Union[Dict, Tuple, Response]: +def registered_api_adapter(app, get_response: Callable[..., Any], **kwargs) -> Union[Dict, Tuple, Response]: """ Calls the registered API using ONLY the **kwargs provided to ensure the call signature of existing defined router of Users does not create a breaking change. @@ -740,7 +743,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): """Route decorator includes parameter `method`""" @@ -1099,7 +1102,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): def register_route(func: Callable): # Convert methods to tuple. It needs to be hashable as its part of the self._routes dict key @@ -1145,7 +1148,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): # NOTE: see #1552 for more context. return super().route(rule.rstrip("/"), method, cors, compress, cache_control) diff --git a/aws_lambda_powertools/event_handler/middlewares/__init__.py b/aws_lambda_powertools/event_handler/middlewares/__init__.py index d85b68d06fd..10c37e8f046 100644 --- a/aws_lambda_powertools/event_handler/middlewares/__init__.py +++ b/aws_lambda_powertools/event_handler/middlewares/__init__.py @@ -1 +1,4 @@ -# Unable to import specific modules due to Cyclic dependency created with api_gateway.py module :-( +from aws_lambda_powertools.event_handler.middlewares.base import BaseMiddlewareHandler +from aws_lambda_powertools.event_handler.middlewares.schema_validation import SchemaValidationMiddleware + +__all__ = ["BaseMiddlewareHandler", "SchemaValidationMiddleware"] diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index 5ba0771edaf..4a86395539c 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -1,5 +1,5 @@ from abc import ABC, abstractmethod -from typing import Callable +from typing import Any, Callable from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response @@ -74,7 +74,14 @@ class BaseMiddlewareHandler(ABC): """ @abstractmethod - def __call__(self, app: ApiGatewayResolver, get_response: Callable, **kwargs) -> Response: + def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **kwargs) -> Response: + """ + The Middleware Handler + + """ + raise NotImplementedError() + + def __call__(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **kwargs) -> Response: """ The Middleware handler function. @@ -83,4 +90,4 @@ def __call__(self, app: ApiGatewayResolver, get_response: Callable, **kwargs) -> :param kwargs: Any additional arguments to pass to the next middleware handler :return: The response from the next middleware handler in the chain """ - raise NotImplementedError() + return self.handler(app, get_response, **kwargs) diff --git a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py new file mode 100644 index 00000000000..6bf910adfd0 --- /dev/null +++ b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py @@ -0,0 +1,59 @@ +import json +from typing import Any, Callable, Dict, Optional + +from aws_lambda_powertools.event_handler import content_types +from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response +from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler +from aws_lambda_powertools.utilities.validation import validate +from aws_lambda_powertools.utilities.validation.exceptions import InvalidSchemaFormatError, SchemaValidationError + + +class SchemaValidationMiddleware(BaseMiddlewareHandler): + """ + Validates the API request body against the provided schema. + + """ + + def __init__(self, schema: Dict, formats: Optional[Dict] = None): + super().__init__() + self.schema = schema + self.formats = formats + + def bad_request(self, error: SchemaValidationError) -> Response: + return Response( + status_code=400, + content_type=content_types.APPLICATION_JSON, + body=json.dumps({"message": error.message}), + ) + + def bad_config(self, error: InvalidSchemaFormatError) -> Response: + return Response( + status_code=500, + content_type=content_types.APPLICATION_JSON, + body=json.dumps({"message": str(error)}), + ) + + def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **kwargs) -> Response: + """ + Validate using Powertools validate() utility. + + Return HTTP 400 Response if validation fails. + Return HTTP 500 Response if validation fails due to invalid schema format. + + Return the next middleware response if validation passes. + + :param app: The ApiGatewayResolver instance + :param get_response: The original response + :param kwargs: Additional arguments + :return: The original response or HTTP 400 Response or HTTP 500 Response. + + """ + try: + validate(event=app.current_event.json_body, schema=self.schema, formats=self.formats) + except SchemaValidationError as error: + return self.bad_request(error) + except InvalidSchemaFormatError as error: + return self.bad_config(error) + + # return next middleware response if validation passes. + return get_response(app, **kwargs) diff --git a/tests/events/apigatewayeSchemaMiddlwareInvalidEvent.json b/tests/events/apigatewayeSchemaMiddlwareInvalidEvent.json new file mode 100644 index 00000000000..13d810870e1 --- /dev/null +++ b/tests/events/apigatewayeSchemaMiddlwareInvalidEvent.json @@ -0,0 +1,81 @@ +{ + "version": "1.0", + "resource": "/my/path", + "path": "/my/path", + "httpMethod": "POST", + "headers": { + "Header1": "value1", + "Header2": "value2", + "Origin": "https://aws.amazon.com" + }, + "multiValueHeaders": { + "Header1": [ + "value1" + ], + "Header2": [ + "value1", + "value2" + ] + }, + "queryStringParameters": { + "parameter1": "value1", + "parameter2": "value" + }, + "multiValueQueryStringParameters": { + "parameter1": [ + "value1", + "value2" + ], + "parameter2": [ + "value" + ] + }, + "requestContext": { + "accountId": "123456789012", + "apiId": "id", + "authorizer": { + "claims": null, + "scopes": null + }, + "domainName": "id.execute-api.us-east-1.amazonaws.com", + "domainPrefix": "id", + "extendedRequestId": "request-id", + "httpMethod": "GET", + "identity": { + "accessKey": null, + "accountId": null, + "caller": null, + "cognitoAuthenticationProvider": null, + "cognitoAuthenticationType": null, + "cognitoIdentityId": null, + "cognitoIdentityPoolId": null, + "principalOrgId": null, + "sourceIp": "192.168.0.1/32", + "user": null, + "userAgent": "user-agent", + "userArn": null, + "clientCert": { + "clientCertPem": "CERT_CONTENT", + "subjectDN": "www.example.com", + "issuerDN": "Example issuer", + "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", + "validity": { + "notBefore": "May 28 12:30:02 2019 GMT", + "notAfter": "Aug 5 09:36:04 2021 GMT" + } + } + }, + "path": "/my/path", + "protocol": "HTTP/1.1", + "requestId": "id=", + "requestTime": "04/Mar/2020:19:15:17 +0000", + "requestTimeEpoch": 1583349317135, + "resourceId": null, + "resourcePath": "/my/path", + "stage": "$default" + }, + "pathParameters": null, + "stageVariables": null, + "body": "{\"username\": \"lessa\"}", + "isBase64Encoded": false +} diff --git a/tests/events/apigatewayeSchemaMiddlwareValidEvent.json b/tests/events/apigatewayeSchemaMiddlwareValidEvent.json new file mode 100644 index 00000000000..454465b9a45 --- /dev/null +++ b/tests/events/apigatewayeSchemaMiddlwareValidEvent.json @@ -0,0 +1,81 @@ +{ + "version": "1.0", + "resource": "/my/path", + "path": "/my/path", + "httpMethod": "POST", + "headers": { + "Header1": "value1", + "Header2": "value2", + "Origin": "https://aws.amazon.com" + }, + "multiValueHeaders": { + "Header1": [ + "value1" + ], + "Header2": [ + "value1", + "value2" + ] + }, + "queryStringParameters": { + "parameter1": "value1", + "parameter2": "value" + }, + "multiValueQueryStringParameters": { + "parameter1": [ + "value1", + "value2" + ], + "parameter2": [ + "value" + ] + }, + "requestContext": { + "accountId": "123456789012", + "apiId": "id", + "authorizer": { + "claims": null, + "scopes": null + }, + "domainName": "id.execute-api.us-east-1.amazonaws.com", + "domainPrefix": "id", + "extendedRequestId": "request-id", + "httpMethod": "GET", + "identity": { + "accessKey": null, + "accountId": null, + "caller": null, + "cognitoAuthenticationProvider": null, + "cognitoAuthenticationType": null, + "cognitoIdentityId": null, + "cognitoIdentityPoolId": null, + "principalOrgId": null, + "sourceIp": "192.168.0.1/32", + "user": null, + "userAgent": "user-agent", + "userArn": null, + "clientCert": { + "clientCertPem": "CERT_CONTENT", + "subjectDN": "www.example.com", + "issuerDN": "Example issuer", + "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", + "validity": { + "notBefore": "May 28 12:30:02 2019 GMT", + "notAfter": "Aug 5 09:36:04 2021 GMT" + } + } + }, + "path": "/my/path", + "protocol": "HTTP/1.1", + "requestId": "id=", + "requestTime": "04/Mar/2020:19:15:17 +0000", + "requestTimeEpoch": 1583349317135, + "resourceId": null, + "resourcePath": "/my/path", + "stage": "$default" + }, + "pathParameters": null, + "stageVariables": null, + "body": "{\"message\": \"hello world\", \"username\": \"lessa\"}", + "isBase64Encoded": false +} diff --git a/tests/functional/event_handler/conftest.py b/tests/functional/event_handler/conftest.py index 3c281ef0d5c..1d95e5fe3bd 100644 --- a/tests/functional/event_handler/conftest.py +++ b/tests/functional/event_handler/conftest.py @@ -7,3 +7,35 @@ def json_dump(): # our serializers reduce length to save on costs; fixture to replicate separators return lambda obj: json.dumps(obj, separators=(",", ":")) + + +@pytest.fixture +def validation_schema(): + return { + "$schema": "http://json-schema.org/draft-07/schema", + "$id": "http://example.com/example.json", + "type": "object", + "title": "Sample schema", + "description": "The root schema comprises the entire JSON document.", + "examples": [{"message": "hello world", "username": "lessa"}], + "required": ["message", "username"], + "properties": { + "message": { + "$id": "#/properties/message", + "type": "string", + "title": "The message", + "examples": ["hello world"], + }, + "username": { + "$id": "#/properties/username", + "type": "string", + "title": "The username", + "examples": ["lessa"], + }, + }, + } + + +@pytest.fixture +def raw_event(): + return {"message": "hello hello", "username": "blah blah"} diff --git a/tests/functional/event_handler/test_api_gateway.py b/tests/functional/event_handler/test_api_gateway.py index 8a659383c40..d6b9a9741a1 100644 --- a/tests/functional/event_handler/test_api_gateway.py +++ b/tests/functional/event_handler/test_api_gateway.py @@ -1847,3 +1847,34 @@ def get_lambda(my_id: str, name: str, injected: str) -> Response: assert result["statusCode"] == 200 assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] assert result["body"] == "path" + + +def test_middleware_early_return(): + # GIVEN + app = ApiGatewayResolver() + + def middleware_one(app, get_response, **kwargs): + # inject a variable into the kwargs + response = get_response(app, injected="injected_value", **kwargs) + + return response + + def early_return_middleware(app, get_response, **kwargs): + assert kwargs.get("injected") == "injected_value" + + return Response(400, content_types.TEXT_HTML, "bad_response") + + @app.get("//", middlewares=[middleware_one, early_return_middleware]) + def get_lambda(my_id: str, name: str, injected: str) -> Response: + assert name == "my" + assert injected == "injected_value" + + return Response(200, content_types.TEXT_HTML, my_id) + + # WHEN calling the event handler + result = app(LOAD_GW_EVENT, {}) + + # THEN + assert result["statusCode"] == 400 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] + assert result["body"] == "bad_response" diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py new file mode 100644 index 00000000000..42db3e573e4 --- /dev/null +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -0,0 +1,63 @@ +from aws_lambda_powertools.event_handler import content_types +from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response +from aws_lambda_powertools.event_handler.middlewares import SchemaValidationMiddleware +from tests.functional.utils import load_event + + +def test_pass_schema_validation(validation_schema): + # GIVEN + app = ApiGatewayResolver() + + @app.post("/my/path", middlewares=[SchemaValidationMiddleware(validation_schema)]) + def post_lambda() -> Response: + return Response(200, content_types.TEXT_HTML, "path") + + # WHEN calling the event handler + result = app(load_event("apigatewayeSchemaMiddlwareValidEvent.json"), {}) + + # THEN + assert result["statusCode"] == 200 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] + assert result["body"] == "path" + + +def test_fail_schema_validation(validation_schema): + # GIVEN + app = ApiGatewayResolver() + + @app.post("/my/path", middlewares=[SchemaValidationMiddleware(validation_schema)]) + def post_lambda() -> Response: + return Response(200, content_types.TEXT_HTML, "Should not be returned") + + # WHEN calling the event handler + result = app(load_event("apigatewayeSchemaMiddlwareInvalidEvent.json"), {}) + print(f"\nRESULT:::{result}") + + # THEN + assert result["statusCode"] == 400 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.APPLICATION_JSON] + assert ( + result["body"] + == "{\"message\": \"Failed schema validation. Error: data must contain ['message'] properties, Path: ['data'], Data: {'username': 'lessa'}\"}" # noqa: E501 + ) + + +def test_invalid_schema_validation(): + # GIVEN + app = ApiGatewayResolver() + + @app.post("/my/path", middlewares=[SchemaValidationMiddleware(schema="schema.json")]) + def post_lambda() -> Response: + return Response(200, content_types.TEXT_HTML, "Should not be returned") + + # WHEN calling the event handler + result = app(load_event("apigatewayeSchemaMiddlwareValidEvent.json"), {}) + + print(f"\nRESULT:::{result}") + # THEN + assert result["statusCode"] == 500 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.APPLICATION_JSON] + assert ( + result["body"] + == "{\"message\": \"Schema received: schema.json, Formats: {}. Error: 'str' object has no attribute 'items'\"}" + ) From 1a90b341c8091ef3e6f28d6c67e42f13a971088f Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Sat, 5 Aug 2023 18:08:40 +1000 Subject: [PATCH 19/85] chore(security): relabel http to https for test JSON Schema (because sonarqube) --- tests/functional/event_handler/conftest.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/tests/functional/event_handler/conftest.py b/tests/functional/event_handler/conftest.py index 1d95e5fe3bd..c7a4ac6e500 100644 --- a/tests/functional/event_handler/conftest.py +++ b/tests/functional/event_handler/conftest.py @@ -12,8 +12,8 @@ def json_dump(): @pytest.fixture def validation_schema(): return { - "$schema": "http://json-schema.org/draft-07/schema", - "$id": "http://example.com/example.json", + "$schema": "https://json-schema.org/draft-07/schema", + "$id": "https://example.com/example.json", "type": "object", "title": "Sample schema", "description": "The root schema comprises the entire JSON document.", From a9d9cb2b4c9b76b40a3e303f2bf948dd68214b5f Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Thu, 10 Aug 2023 23:49:28 +1000 Subject: [PATCH 20/85] Apply suggestions from code review Co-authored-by: Heitor Lessa Signed-off-by: walmsles <2704782+walmsles@users.noreply.github.com> --- .../event_handler/api_gateway.py | 37 +++++++++++++------ .../event_handler/middlewares/base.py | 11 +++--- .../event_handler/test_api_gateway.py | 2 +- 3 files changed, 32 insertions(+), 18 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index d8f096e91ac..10376a0f7cb 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -272,7 +272,7 @@ def build_middleware_stack(self, router_middlewares: List[Callable]) -> None: handler wanting to short-circuit the middlware call chain should raise an execution to force the Python call stack created by the handler call-chain to naturally un-wind. - This becomes a simple concept for Users ot understand and reason with - no additional + This becomes a simple concept for Users to understand and reason with - no additional gymanstics other than plain old try ... except. Notes @@ -416,10 +416,10 @@ def route( def use(self, middlewares: List[Callable[..., Any]]): """ - Add a List of middlewares to the global routetr middleware list + Add a list of middlewares to the global router middleware list - These Middleware handlers will be executed in order of adding to the array and will - be executed before any specific middleware applied at the actual route level. + These middlewares will be called in insertion order and + before any middleware registered at the route level. """ self.router_middlewares = self.router_middlewares + middlewares @@ -597,7 +597,7 @@ def clear_context(self): self.context.clear() -class MiddlewareStackWrapper: +class MiddlewareFrame: """ creates a Middle Stack Wrapper instance to be used as a "Frame" in the overall stack of middleware functions. Each instance contains the current middleware to be executed and the next @@ -622,11 +622,27 @@ class MiddlewareStackWrapper: def __init__( self, - handler: Callable, + current_middleware: Callable, next_middleware: Callable, ) -> None: self.handler: Callable = handler self.next_middleware: Callable = next_middleware + self._next_middleware_name = next_middleware.__name__ + + + @property + def __name__(): + """Current middleware name + + It ensures backward compatibility with view functions being callable. This + improves debugging since we need both current and next middlewares/callable names. + """ + return self.handler.__name__ + + def __str__(self) -> str: + """Identify current middleware identity and call chain for debugging purposes.""" + middleware_name = self.__name__ + return f"Middleware '{middleware_name}'. Call chain is: {middleware_name} -> {self._next_middleware_name}" def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]: """ @@ -642,16 +658,15 @@ def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]: Returns ------- Union[Dict, Tuple, Response] - (tech-debt for backward compatability). The response type should be a - Response object in all cases excepting when the oiginal API rout handler + (tech-debt for backward compatibility). The response type should be a + Response object in all cases excepting when the original API rout handler is executed which will return one of 3 outputs. """ - return self.handler(app, self.next_middleware, **kwargs) + return self.current_middleware(app, self.next_middleware, **kwargs) -# No type checking possible due to Dependency order of definition () -def registered_api_adapter(app, get_response: Callable[..., Any], **kwargs) -> Union[Dict, Tuple, Response]: +def registered_api_adapter(app: "ApiGatewayResolver", get_response: Callable[..., Any], **kwargs) -> Union[Dict, Tuple, Response]: """ Calls the registered API using ONLY the **kwargs provided to ensure the call signature of existing defined router of Users does not create a breaking change. diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index 4a86395539c..2c4f6a0078b 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -16,13 +16,13 @@ class BaseMiddlewareHandler(ABC): ```python # Place code here for actions BEFORE the next middleware handler is called - # or optionally raise an excpetion to short-circuit the middleware execution chain + # 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) - # Place code ehre for actions AFTER the next middleware handler is called + # Place code here for actions AFTER the next middleware handler is called return result ``` @@ -32,16 +32,16 @@ class BaseMiddlewareHandler(ABC): specific types of exceptions. for example: - ============ ```python try: result: Response = get_response(app, my_custom_arg="handled", **kwargs) except MyCustomValidationException as e: - # Make sure we send back a 400 resposne for any Custom Validation Exceptions. + # Make sure we send back a 400 response for any Custom Validation Exceptions. result.status_code = 400 - result.body = {"message": str(e)} + result.body = {"message": "Failed validation"} + logger.exception(f"Failed validation when handling route: {app.current_event.path}") return result ``` @@ -51,7 +51,6 @@ class BaseMiddlewareHandler(ABC): handler to get the response from the next middleware handler in the chain. for example: - ============ If you wanted to ensure API callers cannot call a DELETE verb on your API (regardless of defined routes) you could do so with the following middleware implementation. diff --git a/tests/functional/event_handler/test_api_gateway.py b/tests/functional/event_handler/test_api_gateway.py index d6b9a9741a1..6d11593c65b 100644 --- a/tests/functional/event_handler/test_api_gateway.py +++ b/tests/functional/event_handler/test_api_gateway.py @@ -1853,7 +1853,7 @@ def test_middleware_early_return(): # GIVEN app = ApiGatewayResolver() - def middleware_one(app, get_response, **kwargs): + def middleware_one(app, get_response, **context): # inject a variable into the kwargs response = get_response(app, injected="injected_value", **kwargs) From 10080b54b07c94f287785de664b08f9ffda0900a Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 11 Aug 2023 00:24:17 +1000 Subject: [PATCH 21/85] chore(typing): Ficup typing and function/attribute scopes - keep private private --- .../event_handler/api_gateway.py | 67 ++++++++++++++----- .../event_handler/test_api_gateway.py | 6 +- 2 files changed, 53 insertions(+), 20 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 10376a0f7cb..678c68f9e5a 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -220,6 +220,27 @@ def __init__( cache_control: Optional[str], middlewares: Optional[List[Callable[..., Any]]], ): + """ + + Parameters + ---------- + + method: str + The HTTP method, example "GET" + rule: Pattern + The route rule, example "/my/path" + func: Callable + The route handler function + cors: bool + Whether or not to enable CORS for this route + compress: bool + Whether or not to enable gzip compression for this route + cache_control: Optional[str] + The cache control header value, example "max-age=3600" + middlewares: Optional[List[Callable[..., Any]]] + The list of route middlewares to execute. These are executed in the order they are + provided. + """ self.method = method.upper() self.rule = rule self.func = func @@ -228,7 +249,10 @@ def __init__( self.cache_control = cache_control self.middlewares = middlewares or [] - self.middleware_stack_built = False + """ + _middleware_stack_built is used to ensure the middleware stack is only built once. + """ + self._middleware_stack_built = False def __call__( self, @@ -257,12 +281,18 @@ def __call__( Returns an API Response object in ALL cases, excepting when the original API route handler is executed which may also return a Dict or Tuple response. """ - if not self.middleware_stack_built: - self.build_middleware_stack(router_middlewares=router_middlewares) + """ + Check self._middleware_stack_built to ensure the middleware stack is only built once. + This will save CPU execution time when API route is executed multiple times. + """ + if not self._middleware_stack_built: + self._build_middleware_stack(router_middlewares=router_middlewares) + + # Call the Middleware Wrapped route function handler with the app and route arguments return self.func(app, **route_arguments) - def build_middleware_stack(self, router_middlewares: List[Callable]) -> None: + def _build_middleware_stack(self, router_middlewares: List[Callable]) -> None: """ Builds the middleware execution stack for the handler by wrapping each handler in an instance of MiddlewareWrapper which is used to contain the state @@ -292,7 +322,7 @@ def build_middleware_stack(self, router_middlewares: List[Callable]) -> None: # need to change (avoid breaking changes) # 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 - all_middlewares.append(registered_api_adapter) + all_middlewares.append(_registered_api_adapter) # Wrap the original route handler function in the middleware handlers # using the MiddlewareWrapper class callable construct in reverse order to @@ -300,9 +330,9 @@ 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.func = MiddlewareStackWrapper(handler=handler, next_middleware=self.func) + self.func = MiddlewareFrame(current_middleware=handler, next_middleware=self.func) - self.middleware_stack_built = True + self._middleware_stack_built = True class ResponseBuilder: @@ -418,7 +448,7 @@ def use(self, middlewares: List[Callable[..., Any]]): """ Add a list of middlewares to the global router middleware list - These middlewares will be called in insertion order and + These middlewares will be called in insertion order and before any middleware registered at the route level. """ self.router_middlewares = self.router_middlewares + middlewares @@ -622,22 +652,21 @@ class MiddlewareFrame: def __init__( self, - current_middleware: Callable, - next_middleware: Callable, + current_middleware: Callable[..., Any], + next_middleware: Callable[..., Any], ) -> None: - self.handler: Callable = handler - self.next_middleware: Callable = next_middleware + self.current_middleware: Callable[..., Any] = current_middleware + self.next_middleware: Callable[..., Any] = next_middleware self._next_middleware_name = next_middleware.__name__ - @property - def __name__(): + def __name__(self): # noqa: A003 """Current middleware name - + It ensures backward compatibility with view functions being callable. This improves debugging since we need both current and next middlewares/callable names. """ - return self.handler.__name__ + return self.current_middleware.__name__ def __str__(self) -> str: """Identify current middleware identity and call chain for debugging purposes.""" @@ -666,7 +695,11 @@ def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]: return self.current_middleware(app, self.next_middleware, **kwargs) -def registered_api_adapter(app: "ApiGatewayResolver", get_response: Callable[..., Any], **kwargs) -> Union[Dict, Tuple, Response]: +def _registered_api_adapter( + app: "ApiGatewayResolver", + get_response: Callable[..., Any], + **kwargs, +) -> Union[Dict, Tuple, Response]: """ Calls the registered API using ONLY the **kwargs provided to ensure the call signature of existing defined router of Users does not create a breaking change. diff --git a/tests/functional/event_handler/test_api_gateway.py b/tests/functional/event_handler/test_api_gateway.py index 6d11593c65b..3893c52824c 100644 --- a/tests/functional/event_handler/test_api_gateway.py +++ b/tests/functional/event_handler/test_api_gateway.py @@ -1855,12 +1855,12 @@ def test_middleware_early_return(): def middleware_one(app, get_response, **context): # inject a variable into the kwargs - response = get_response(app, injected="injected_value", **kwargs) + response = get_response(app, injected="injected_value", **context) return response - def early_return_middleware(app, get_response, **kwargs): - assert kwargs.get("injected") == "injected_value" + def early_return_middleware(app, get_response, **context): + assert context.get("injected") == "injected_value" return Response(400, content_types.TEXT_HTML, "bad_response") From de7247d4bce0bc7430d2e6790ce10b3e84e67438 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 11 Aug 2023 00:46:33 +1000 Subject: [PATCH 22/85] feat(middlewares): Add optional outbound schema dn formats to schema validation, also fixup naming convention for clarity --- .../middlewares/schema_validation.py | 37 ++++++++++++++++--- .../event_handler/test_api_middlewares.py | 4 +- 2 files changed, 33 insertions(+), 8 deletions(-) diff --git a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py index 6bf910adfd0..73c7c1854de 100644 --- a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py +++ b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py @@ -14,16 +14,31 @@ class SchemaValidationMiddleware(BaseMiddlewareHandler): """ - def __init__(self, schema: Dict, formats: Optional[Dict] = None): + def __init__( + self, + inbound_schema: Dict, + inbound_formats: Optional[Dict] = None, + outbound_schema: Optional[Dict] = None, + outbound_formats: Optional[Dict] = None, + ): super().__init__() - self.schema = schema - self.formats = formats + self.inbound_schema = inbound_schema + self.inbound_formats = inbound_formats + self.outbound_schema = outbound_schema + self.outbound_formats = outbound_formats + + def bad_response(self, error: SchemaValidationError) -> Response: + return Response( + status_code=400, + content_type=content_types.APPLICATION_JSON, + body=json.dumps({"message": f"Bad Response: {error.message}"}), + ) def bad_request(self, error: SchemaValidationError) -> Response: return Response( status_code=400, content_type=content_types.APPLICATION_JSON, - body=json.dumps({"message": error.message}), + body=json.dumps({"message": f"Bad Request: {error.message}"}), ) def bad_config(self, error: InvalidSchemaFormatError) -> Response: @@ -49,11 +64,21 @@ def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **k """ try: - validate(event=app.current_event.json_body, schema=self.schema, formats=self.formats) + validate(event=app.current_event.json_body, schema=self.inbound_schema, formats=self.inbound_formats) except SchemaValidationError as error: return self.bad_request(error) except InvalidSchemaFormatError as error: return self.bad_config(error) # return next middleware response if validation passes. - return get_response(app, **kwargs) + result: Response = get_response(app, **kwargs) + + if self.outbound_formats is not None: + try: + validate(event=result.body, schema=self.inbound_schema, formats=self.inbound_formats) + except SchemaValidationError as error: + return self.bad_response(error) + except InvalidSchemaFormatError as error: + return self.bad_config(error) + + return result diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index 42db3e573e4..a20a51fbc93 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -38,7 +38,7 @@ def post_lambda() -> Response: assert result["multiValueHeaders"]["Content-Type"] == [content_types.APPLICATION_JSON] assert ( result["body"] - == "{\"message\": \"Failed schema validation. Error: data must contain ['message'] properties, Path: ['data'], Data: {'username': 'lessa'}\"}" # noqa: E501 + == "{\"message\": \"Bad Request: Failed schema validation. Error: data must contain ['message'] properties, Path: ['data'], Data: {'username': 'lessa'}\"}" # noqa: E501 ) @@ -46,7 +46,7 @@ def test_invalid_schema_validation(): # GIVEN app = ApiGatewayResolver() - @app.post("/my/path", middlewares=[SchemaValidationMiddleware(schema="schema.json")]) + @app.post("/my/path", middlewares=[SchemaValidationMiddleware(inbound_schema="schema.json")]) def post_lambda() -> Response: return Response(200, content_types.TEXT_HTML, "Should not be returned") From dbae938f59a04e51dce2c9d38ecfc378b52080ff Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 11 Aug 2023 00:57:03 +1000 Subject: [PATCH 23/85] fix(errors): add logger for config exceptions and return minimal details --- .../event_handler/middlewares/schema_validation.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py index 73c7c1854de..1b34302494a 100644 --- a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py +++ b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py @@ -1,4 +1,5 @@ import json +import logging from typing import Any, Callable, Dict, Optional from aws_lambda_powertools.event_handler import content_types @@ -7,6 +8,8 @@ from aws_lambda_powertools.utilities.validation import validate from aws_lambda_powertools.utilities.validation.exceptions import InvalidSchemaFormatError, SchemaValidationError +logger = logging.getLogger(__name__) + class SchemaValidationMiddleware(BaseMiddlewareHandler): """ @@ -42,10 +45,11 @@ def bad_request(self, error: SchemaValidationError) -> Response: ) def bad_config(self, error: InvalidSchemaFormatError) -> Response: + logger.debug(f"Invalid Schema Format: {error}") return Response( status_code=500, content_type=content_types.APPLICATION_JSON, - body=json.dumps({"message": str(error)}), + body=json.dumps({"message": "Internal Server Error"}), ) def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **kwargs) -> Response: From 13df1220e1dab2d690502c950712cfb1358d1418 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 11 Aug 2023 01:10:06 +1000 Subject: [PATCH 24/85] chore(docs): fixup format of docstrings to numpy format --- .../event_handler/middlewares/base.py | 37 ++++++++++++++----- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index 2c4f6a0078b..2fc94fbba69 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -64,12 +64,6 @@ class BaseMiddlewareHandler(ABC): # Call the next middleware in the chain (needed for when condition above is valid) return get_response(app, **kwargs) - - :param app: The ApiGatewayResolver object - :param get_response: The next middleware handler in the chain - :param kwargs: Any additional arguments to pass to the next middleware handler - :return: The response from the next middleware handler in the chain - """ @abstractmethod @@ -77,6 +71,20 @@ def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **k """ The Middleware Handler + Parameters + ---------- + app: ApiGatewayResolver + The ApiGatewayResolver object + get_response: Callable[..., Any] + The next middleware handler in the chain + kwargs: Any + Any additional arguments to pass to the next middleware handler + + Returns + ------- + Response + The response from the next middleware handler in the chain + """ raise NotImplementedError() @@ -84,9 +92,18 @@ def __call__(self, app: ApiGatewayResolver, get_response: Callable[..., Any], ** """ The Middleware handler function. - :param app: The ApiGatewayResolver object - :param get_response: The next middleware handler in the chain - :param kwargs: Any additional arguments to pass to the next middleware handler - :return: The response from the next middleware handler in the chain + Parameters + ---------- + app: ApiGatewayResolver + The ApiGatewayResolver object + get_response: Callable[...,Any] + 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) From 806711667722bedb32f625b8e9988537452d5179 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 11 Aug 2023 01:19:57 +1000 Subject: [PATCH 25/85] chore(docs): change docstrings to numpy format --- .../event_handler/api_gateway.py | 22 ++++++++++++++----- 1 file changed, 16 insertions(+), 6 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 678c68f9e5a..6d80c237500 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -704,13 +704,23 @@ def _registered_api_adapter( Calls the registered API using ONLY the **kwargs provided to ensure the call signature of existing defined router of Users does not create a breaking change. - :param app: The API Gateway resolver - :param get_response: The function to handle the API - :param kwargs: The arguments to pass to the API - :return: The API Response Object - - This middleware enables backward compatibility for the existing API routes model in Powertools + **IMPORTANT: This middleware enables backward compatibility for the existing API routes model in Powertools and it MUST BE THE LAST middleware in the middleware stack. + + Parameters + ---------- + app: ApiGatewayResolver + The API Gateway resolver + get_response: Callable[..., Any] + The function to handle the API + **kwargs: + The arguments to pass to the API + + Returns + ------- + Response + The API Response Object + """ return app._to_response(get_response(**kwargs)) From 6ce64f128d12dc703cd9d00564e82a4786a616d5 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 11 Aug 2023 20:52:34 +1000 Subject: [PATCH 26/85] fix(tests): fix failing tests due to resposne change: --- tests/functional/event_handler/test_api_middlewares.py | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index a20a51fbc93..c3c289487ad 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -57,7 +57,4 @@ def post_lambda() -> Response: # THEN assert result["statusCode"] == 500 assert result["multiValueHeaders"]["Content-Type"] == [content_types.APPLICATION_JSON] - assert ( - result["body"] - == "{\"message\": \"Schema received: schema.json, Formats: {}. Error: 'str' object has no attribute 'items'\"}" - ) + assert result["body"] == '{"message": "Internal Server Error"}' From 22b83e0799371a505b9e9b54d87b612a9edda2cf Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 11 Aug 2023 21:10:28 +1000 Subject: [PATCH 27/85] chore(tests): group middleware testing to one module --- .../event_handler/test_api_gateway.py | 129 ---------------- .../event_handler/test_api_middlewares.py | 140 +++++++++++++++++- 2 files changed, 139 insertions(+), 130 deletions(-) diff --git a/tests/functional/event_handler/test_api_gateway.py b/tests/functional/event_handler/test_api_gateway.py index 3893c52824c..2afd1241bed 100644 --- a/tests/functional/event_handler/test_api_gateway.py +++ b/tests/functional/event_handler/test_api_gateway.py @@ -1749,132 +1749,3 @@ def static_handler() -> Response: # THEN the static_handler should have been called, because it fully matches the path directly response_body = json.loads(response["body"]) assert response_body["hello"] == "static" - - -def test_route_with_middleware(): - # GIVEN a Rest API Gateway proxy type event - app = ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent) - - # define custom middleware to inject new argument - "custom" - def middleware_1(app, get_response, **kwargs): - # inject a variable into the kwargs - response = get_response(app, custom="custom", **kwargs) - - return response - - # define custom middleware to inject new argument - "another_one" - def middleware_2(app, get_response, **kwargs): - # inject a variable into the kwargs - response = get_response(app, another_one=6, **kwargs) - - return response - - @app.get("/my/path", middlewares=[middleware_1, middleware_2]) - def get_lambda(another_one: int, custom: str) -> Response: - assert isinstance(app.current_event, APIGatewayProxyEvent) - assert another_one == 6 - assert custom == "custom" - return Response(200, content_types.TEXT_HTML, "foo") - - # WHEN calling the event handler - result = app(LOAD_GW_EVENT, {}) - - # THEN process event correctly - # AND set the current_event type as APIGatewayProxyEvent - assert result["statusCode"] == 200 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] - assert result["body"] == "foo" - - -def test_with_router_middleware(): - # GIVEN a Rest API Gateway proxy type event - app = ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent) - - # define custom middleware to inject new argument - "custom" - def middleware_1(app, get_response, **kwargs): - # inject a variable into the kwargs - response = get_response(app, custom="custom", **kwargs) - - return response - - # define custom middleware to inject new argument - "another_one" - def middleware_2(app, get_response, **kwargs): - # inject a variable into the kwargs - response = get_response(app, another_one=6, **kwargs) - - return response - - app.use([middleware_1, middleware_2]) - - @app.get("/my/path") - def get_lambda(another_one: int, custom: str) -> Response: - assert isinstance(app.current_event, APIGatewayProxyEvent) - assert another_one == 6 - assert custom == "custom" - return Response(200, content_types.TEXT_HTML, "foo") - - # WHEN calling the event handler - result = app(LOAD_GW_EVENT, {}) - - # THEN process event correctly - # AND set the current_event type as APIGatewayProxyEvent - assert result["statusCode"] == 200 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] - assert result["body"] == "foo" - - -def test_dynamic_route_with_middleware(): - # GIVEN - app = ApiGatewayResolver() - - def middleware_one(app, get_response, **kwargs): - # inject a variable into the kwargs - response = get_response(app, injected="injected_value", **kwargs) - - return response - - @app.get("//", middlewares=[middleware_one]) - def get_lambda(my_id: str, name: str, injected: str) -> Response: - assert name == "my" - assert injected == "injected_value" - - return Response(200, content_types.TEXT_HTML, my_id) - - # WHEN calling the event handler - result = app(LOAD_GW_EVENT, {}) - - # THEN - assert result["statusCode"] == 200 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] - assert result["body"] == "path" - - -def test_middleware_early_return(): - # GIVEN - app = ApiGatewayResolver() - - def middleware_one(app, get_response, **context): - # inject a variable into the kwargs - response = get_response(app, injected="injected_value", **context) - - return response - - def early_return_middleware(app, get_response, **context): - assert context.get("injected") == "injected_value" - - return Response(400, content_types.TEXT_HTML, "bad_response") - - @app.get("//", middlewares=[middleware_one, early_return_middleware]) - def get_lambda(my_id: str, name: str, injected: str) -> Response: - assert name == "my" - assert injected == "injected_value" - - return Response(200, content_types.TEXT_HTML, my_id) - - # WHEN calling the event handler - result = app(LOAD_GW_EVENT, {}) - - # THEN - assert result["statusCode"] == 400 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] - assert result["body"] == "bad_response" diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index c3c289487ad..ea8f9764265 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -1,8 +1,146 @@ from aws_lambda_powertools.event_handler import content_types -from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response +from aws_lambda_powertools.event_handler.api_gateway import ( + ApiGatewayResolver, + ProxyEventType, + Response, +) from aws_lambda_powertools.event_handler.middlewares import SchemaValidationMiddleware +from aws_lambda_powertools.utilities.data_classes import ( + APIGatewayProxyEvent, +) from tests.functional.utils import load_event +LOAD_GW_EVENT = load_event("apiGatewayProxyEvent.json") + + +def test_route_with_middleware(): + # GIVEN a Rest API Gateway proxy type event + app = ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent) + + # define custom middleware to inject new argument - "custom" + def middleware_1(app, get_response, **kwargs): + # inject a variable into the kwargs + response = get_response(app, custom="custom", **kwargs) + + return response + + # define custom middleware to inject new argument - "another_one" + def middleware_2(app, get_response, **kwargs): + # inject a variable into the kwargs + response = get_response(app, another_one=6, **kwargs) + + return response + + @app.get("/my/path", middlewares=[middleware_1, middleware_2]) + def get_lambda(another_one: int, custom: str) -> Response: + assert isinstance(app.current_event, APIGatewayProxyEvent) + assert another_one == 6 + assert custom == "custom" + return Response(200, content_types.TEXT_HTML, "foo") + + # WHEN calling the event handler + result = app(LOAD_GW_EVENT, {}) + + # THEN process event correctly + # AND set the current_event type as APIGatewayProxyEvent + assert result["statusCode"] == 200 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] + assert result["body"] == "foo" + + +def test_with_router_middleware(): + # GIVEN a Rest API Gateway proxy type event + app = ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent) + + # define custom middleware to inject new argument - "custom" + def middleware_1(app, get_response, **kwargs): + # inject a variable into the kwargs + response = get_response(app, custom="custom", **kwargs) + + return response + + # define custom middleware to inject new argument - "another_one" + def middleware_2(app, get_response, **kwargs): + # inject a variable into the kwargs + response = get_response(app, another_one=6, **kwargs) + + return response + + app.use([middleware_1, middleware_2]) + + @app.get("/my/path") + def get_lambda(another_one: int, custom: str) -> Response: + assert isinstance(app.current_event, APIGatewayProxyEvent) + assert another_one == 6 + assert custom == "custom" + return Response(200, content_types.TEXT_HTML, "foo") + + # WHEN calling the event handler + result = app(LOAD_GW_EVENT, {}) + + # THEN process event correctly + # AND set the current_event type as APIGatewayProxyEvent + assert result["statusCode"] == 200 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] + assert result["body"] == "foo" + + +def test_dynamic_route_with_middleware(): + # GIVEN + app = ApiGatewayResolver() + + def middleware_one(app, get_response, **kwargs): + # inject a variable into the kwargs + response = get_response(app, injected="injected_value", **kwargs) + + return response + + @app.get("//", middlewares=[middleware_one]) + def get_lambda(my_id: str, name: str, injected: str) -> Response: + assert name == "my" + assert injected == "injected_value" + + return Response(200, content_types.TEXT_HTML, my_id) + + # WHEN calling the event handler + result = app(LOAD_GW_EVENT, {}) + + # THEN + assert result["statusCode"] == 200 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] + assert result["body"] == "path" + + +def test_middleware_early_return(): + # GIVEN + app = ApiGatewayResolver() + + def middleware_one(app, get_response, **context): + # inject a variable into the kwargs + response = get_response(app, injected="injected_value", **context) + + return response + + def early_return_middleware(app, get_response, **context): + assert context.get("injected") == "injected_value" + + return Response(400, content_types.TEXT_HTML, "bad_response") + + @app.get("//", middlewares=[middleware_one, early_return_middleware]) + def get_lambda(my_id: str, name: str, injected: str) -> Response: + assert name == "my" + assert injected == "injected_value" + + return Response(200, content_types.TEXT_HTML, my_id) + + # WHEN calling the event handler + result = app(LOAD_GW_EVENT, {}) + + # THEN + assert result["statusCode"] == 400 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] + assert result["body"] == "bad_response" + def test_pass_schema_validation(validation_schema): # GIVEN From af719f475a589cc6e5f576b022e042dec7c7a1ef Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Sun, 13 Aug 2023 20:54:15 +1000 Subject: [PATCH 28/85] chore(docs): api_agteway - improve docs for middleware and examples feat(middleware): track middleware frame executions chore(middleware): rename params for developer clarity fix(middleware): additional debug for middleware frame execution chore(middlewares): keep private things private fix(middleware): base middleware - implement __name__ attribute for debug purposes fix(middleware): SchemaValidationMiddleware - refactor error handling to use HTTPError exceptions rather than Response returns for clarity and better Dev UX chore(tests): Improve testing for middlewares - Router coverage, improved coverage for short-circuit cases and HTTPError short circuit handling. --- .../event_handler/api_gateway.py | 78 +++++++++++---- .../event_handler/middlewares/base.py | 4 + .../middlewares/schema_validation.py | 25 ++--- .../event_handler/test_api_middlewares.py | 99 ++++++++++++++++++- 4 files changed, 167 insertions(+), 39 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 6d80c237500..5965ab68686 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -257,7 +257,7 @@ def __init__( def __call__( self, router_middlewares: List[Callable], - app, + app: "ApiGatewayResolver", route_arguments: Dict[str, str], ) -> Union[Dict, Tuple, Response]: """Calling the Router class instance will trigger the following actions: @@ -289,6 +289,9 @@ def __call__( if not self._middleware_stack_built: self._build_middleware_stack(router_middlewares=router_middlewares) + # Keep track of executed middleware + app._append_executed_middleware(self.func.__name__) + # Call the Middleware Wrapped route function handler with the app and route arguments return self.func(app, **route_arguments) @@ -430,7 +433,7 @@ class BaseRouter(ABC): current_event: BaseProxyEvent lambda_context: LambdaContext context: dict - router_middlewares: List[Callable] = [] + _router_middlewares: List[Callable] = [] @abstractmethod def route( @@ -444,14 +447,35 @@ def route( ): raise NotImplementedError() - def use(self, middlewares: List[Callable[..., Any]]): + def use(self, middlewares: List[Callable[..., Any]]) -> None: """ Add a list of middlewares to the global router middleware list These middlewares will be called in insertion order and before any middleware registered at the route level. + + Example + ------- + Add middlewares to be used for every reuqest processed by the Router. + + ``` + my_custom_middleware = new CustomMiddleware() + + app.use([my_custom_middleware]) + + ``` + + Parameters + ---------- + middlewares - List of middlewares to be used + + Returns + ------- + None + + """ - self.router_middlewares = self.router_middlewares + middlewares + self._router_middlewares = self._router_middlewares + middlewares def get( self, @@ -644,8 +668,8 @@ class MiddlewareFrame: Parameters ---------- - handler : Callable - The API route handler to be invoked when this class is executed. + current_middleware : Callable + The current middleware function to be called as a request is processed. next_middleware : Callable The next middleware in the middleware stack. """ @@ -675,24 +699,30 @@ def __str__(self) -> str: def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]: """ - Call the middleware stack wrapper + Call the middleware Frame to process the request. Parameters ---------- app: BaseRouter The router instance **kwargs - Any additional arguments to pass to the middleware stack wrapper + Any additional arguments to pass to the middleware Frame Returns ------- Union[Dict, Tuple, Response] (tech-debt for backward compatibility). The response type should be a - Response object in all cases excepting when the original API rout handler + Response object in all cases excepting when the original API route handler is executed which will return one of 3 outputs. """ - return self.current_middleware(app, self.next_middleware, **kwargs) + logger.debug(f"MiddlewareFrame: {self}") + try: + return self.current_middleware(app, self.next_middleware, **kwargs) + except Exception as error: + # Log the exception and raise it back to the caller + logger.exception(error) + raise error def _registered_api_adapter( @@ -701,11 +731,11 @@ def _registered_api_adapter( **kwargs, ) -> Union[Dict, Tuple, Response]: """ - Calls the registered API using ONLY the **kwargs provided to ensure the - call signature of existing defined router of Users does not create a breaking change. + Calls the registered API using ONLY the **kwargs provided to ensure the last call + in the chain will match the API route function signature. - **IMPORTANT: This middleware enables backward compatibility for the existing API routes model in Powertools - and it MUST BE THE LAST middleware in the middleware stack. + **IMPORTANT: This middleware ensures the actual API route is called with the correct call signature + and it MUST be the final frame in the middleware stack. Parameters ---------- @@ -722,6 +752,7 @@ def _registered_api_adapter( The API Response Object """ + logger.debug(f"Calling API Route Handler: {kwargs}") return app._to_response(get_response(**kwargs)) @@ -789,6 +820,7 @@ def __init__( self._cors_methods: Set[str] = {"OPTIONS"} self._debug = self._has_debug(debug) self._strip_prefixes = strip_prefixes + self._executed_middlewares: List[str] = [] self.context: Dict = {} # early init as customers might add context before event resolution # Allow for a custom serializer or a concise json serialization @@ -880,6 +912,9 @@ def resolve(self, event, context) -> Dict[str, Any]: self.clear_context() return response + def _append_executed_middleware(self, name: str): + self._executed_middlewares.append(name) + def __call__(self, event, context) -> Any: return self.resolve(event, context) @@ -1017,9 +1052,11 @@ def _not_found(self, method: str) -> ResponseBuilder: def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> ResponseBuilder: """Actually call the matching route with any provided keyword arguments.""" try: + # Reset Executed Middleware (for debugging purposes) + self._executed_middlewares = [] return ResponseBuilder( self._to_response( - route(router_middlewares=self.router_middlewares, app=self, route_arguments=route_arguments), + route(router_middlewares=self._router_middlewares, app=self, route_arguments=route_arguments), ), route, ) @@ -1130,6 +1167,10 @@ def include_router(self, router: "Router", prefix: Optional[str] = None) -> None # Merge app and router context self.context.update(**router.context) + + # Add router middlewares to parent ApiGatewayResolver + self._router_middlewares = self._router_middlewares + router._router_middlewares + # use pointer to allow context clearance after event is processed e.g., resolve(evt, ctx) router.context = self.context @@ -1141,7 +1182,10 @@ def include_router(self, router: "Router", prefix: Optional[str] = None) -> None rule = prefix if rule == "/" else f"{prefix}{rule}" new_route = (rule, *route[1:]) - self.route(*new_route)(func) + # Middlewares are stored by route seperately - must grab them to include + middlewares = router._routes_with_middleware.get(new_route) + + self.route(*new_route, middlewares=middlewares)(func) # type: ignore class Router(BaseRouter): @@ -1209,7 +1253,7 @@ def route( middlewares: Optional[List[Callable[..., Any]]] = None, ): # NOTE: see #1552 for more context. - return super().route(rule.rstrip("/"), method, cors, compress, cache_control) + return super().route(rule.rstrip("/"), method, cors, compress, cache_control, middlewares) # Override _compile_regex to exclude trailing slashes for route resolution @staticmethod diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index 2fc94fbba69..7b910a31651 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -88,6 +88,10 @@ def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **k """ raise NotImplementedError() + @property + def __name__(self) -> str: # noqa A003 + return str(self.__class__.__name__) + def __call__(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **kwargs) -> Response: """ The Middleware handler function. diff --git a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py index 1b34302494a..be40520f53b 100644 --- a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py +++ b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py @@ -1,9 +1,8 @@ -import json import logging from typing import Any, Callable, Dict, Optional -from aws_lambda_powertools.event_handler import content_types from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response +from aws_lambda_powertools.event_handler.exceptions import BadRequestError, InternalServerError from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler from aws_lambda_powertools.utilities.validation import validate from aws_lambda_powertools.utilities.validation.exceptions import InvalidSchemaFormatError, SchemaValidationError @@ -31,26 +30,18 @@ def __init__( self.outbound_formats = outbound_formats def bad_response(self, error: SchemaValidationError) -> Response: - return Response( - status_code=400, - content_type=content_types.APPLICATION_JSON, - body=json.dumps({"message": f"Bad Response: {error.message}"}), - ) + message: str = f"Bad Response: {error.message}" + logger.debug(message) + raise BadRequestError(message) def bad_request(self, error: SchemaValidationError) -> Response: - return Response( - status_code=400, - content_type=content_types.APPLICATION_JSON, - body=json.dumps({"message": f"Bad Request: {error.message}"}), - ) + message: str = f"Bad Request: {error.message}" + logger.debug(message) + raise BadRequestError(message) def bad_config(self, error: InvalidSchemaFormatError) -> Response: logger.debug(f"Invalid Schema Format: {error}") - return Response( - status_code=500, - content_type=content_types.APPLICATION_JSON, - body=json.dumps({"message": "Internal Server Error"}), - ) + raise InternalServerError("Internal Server Error") def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **kwargs) -> Response: """ diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index ea8f9764265..9751ef5186e 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -3,7 +3,9 @@ ApiGatewayResolver, ProxyEventType, Response, + Router, ) +from aws_lambda_powertools.event_handler.exceptions import BadRequestError from aws_lambda_powertools.event_handler.middlewares import SchemaValidationMiddleware from aws_lambda_powertools.utilities.data_classes import ( APIGatewayProxyEvent, @@ -66,9 +68,9 @@ def middleware_2(app, get_response, **kwargs): return response - app.use([middleware_1, middleware_2]) + app.use([middleware_1]) - @app.get("/my/path") + @app.get("/my/path", middlewares=[middleware_2]) def get_lambda(another_one: int, custom: str) -> Response: assert isinstance(app.current_event, APIGatewayProxyEvent) assert another_one == 6 @@ -126,7 +128,11 @@ def early_return_middleware(app, get_response, **context): return Response(400, content_types.TEXT_HTML, "bad_response") - @app.get("//", middlewares=[middleware_one, early_return_middleware]) + def not_executed_middleware(app, get_response, **context): + # This should never be executed - if it is an excpetion will be raised + raise NotImplementedError() + + @app.get("//", middlewares=[middleware_one, early_return_middleware, not_executed_middleware]) def get_lambda(my_id: str, name: str, injected: str) -> Response: assert name == "my" assert injected == "injected_value" @@ -176,7 +182,7 @@ def post_lambda() -> Response: assert result["multiValueHeaders"]["Content-Type"] == [content_types.APPLICATION_JSON] assert ( result["body"] - == "{\"message\": \"Bad Request: Failed schema validation. Error: data must contain ['message'] properties, Path: ['data'], Data: {'username': 'lessa'}\"}" # noqa: E501 + == "{\"statusCode\":400,\"message\":\"Bad Request: Failed schema validation. Error: data must contain ['message'] properties, Path: ['data'], Data: {'username': 'lessa'}\"}" # noqa: E501 ) @@ -195,4 +201,87 @@ def post_lambda() -> Response: # THEN assert result["statusCode"] == 500 assert result["multiValueHeaders"]["Content-Type"] == [content_types.APPLICATION_JSON] - assert result["body"] == '{"message": "Internal Server Error"}' + assert result["body"] == '{"statusCode":500,"message":"Internal Server Error"}' + + +def test_middleware_short_circuit_via_httperrors(): + # GIVEN + app = ApiGatewayResolver() + + def middleware_one(app, get_response, **context): + # inject a variable into the kwargs of the middleware chain + response = get_response(app, injected="injected_value", **context) + + return response + + def early_return_middleware(app, get_response, **context): + # ensure "injected" context variable is passed in by middleware_one + assert context.get("injected") == "injected_value" + raise BadRequestError("bad_response") + + def not_executed_middleware(app, get_response, **context): + # This should never be executed - if it is an excpetion will be raised + raise NotImplementedError() + + @app.get("//", middlewares=[middleware_one, early_return_middleware, not_executed_middleware]) + def get_lambda(my_id: str, name: str, injected: str) -> Response: + assert name == "my" + assert injected == "injected_value" + + return Response(200, content_types.TEXT_HTML, my_id) + + # WHEN calling the event handler + result = app(LOAD_GW_EVENT, {}) + + # THEN + assert result["statusCode"] == 400 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.APPLICATION_JSON] + assert result["body"] == '{"statusCode":400,"message":"bad_response"}' + + +def test_api_gateway_app_router_with_middlewares(): + # GIVEN a Router with registered routes + app = ApiGatewayResolver() + router = Router() + + def app_middleware(app, get_response, **context): + # inject a variable into the kwargs of the middleware chain + response = get_response(app, app_injected="app_value", **context) + + return response + + app.use(middlewares=[app_middleware]) + + def router_middleware(app, get_response, **context): + # inject a variable into the kwargs of the middleware chain + response = get_response(app, router_injected="router_value", **context) + + return response + + router.use(middlewares=[router_middleware]) + + def middleware_one(app, get_response, **context): + # inject a variable into the kwargs of the middleware chain + response = get_response(app, injected="injected_value", **context) + + return response + + @router.get("/my/path", middlewares=[middleware_one]) + def foo(app_injected: str, router_injected: str, injected: str): + # make sure value is injected by middleware_one + assert injected == "injected_value" + assert router_injected == "router_value" + assert app_injected == "app_value" + + return Response(200, content_types.TEXT_HTML, "foo") + + return {} + + app.include_router(router) + # WHEN calling the event handler after applying routes from router object + result = app(LOAD_GW_EVENT, {}) + + # THEN process event correctly + assert result["statusCode"] == 200 + assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] + assert result["body"] == "foo" From 0adfc70dc102936581d0a8bf440507f4fc0c1b92 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Sun, 13 Aug 2023 21:24:42 +1000 Subject: [PATCH 29/85] chore(docs): document why mypy 'type: ignore' is used here --- aws_lambda_powertools/event_handler/api_gateway.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 5965ab68686..10a557111e2 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -1185,6 +1185,11 @@ def include_router(self, router: "Router", prefix: Optional[str] = None) -> None # Middlewares are stored by route seperately - must grab them to include middlewares = router._routes_with_middleware.get(new_route) + # Need to use "type: ignore" here since mypy does not like a named parameter after + # tuple expansion since may cause duplicate named parameters in the function signature. + # In this case this is not possible since the tuple expansion is from a hashable source + # and the `middlewares` List is a non-hashable structure so will never be included. + # Still need to ignore for mypy checks or will cause failures (false-positive) self.route(*new_route, middlewares=middlewares)(func) # type: ignore From 63db815af5cd645d5a78b4f86530aa467b7f8d7f Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Mon, 14 Aug 2023 09:12:54 +1000 Subject: [PATCH 30/85] feat(api_middleware): add source diagram for middlewares docs --- docs/diagram_src/api-middlewares.drawio | 828 ++++++++++++++++++++++++ 1 file changed, 828 insertions(+) create mode 100644 docs/diagram_src/api-middlewares.drawio diff --git a/docs/diagram_src/api-middlewares.drawio b/docs/diagram_src/api-middlewares.drawio new file mode 100644 index 00000000000..9011fc8cd2f --- /dev/null +++ b/docs/diagram_src/api-middlewares.drawio @@ -0,0 +1,828 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From 3131f3e92b86954b0e6a46fc9778b1319bb964f4 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Mon, 14 Aug 2023 09:28:38 +1000 Subject: [PATCH 31/85] fix(tests): fix unreachable code --- .../event_handler/test_api_middlewares.py | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index 9751ef5186e..13336f61b68 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -260,22 +260,22 @@ def router_middleware(app, get_response, **context): router.use(middlewares=[router_middleware]) + to_inject: str = "injected_value" + def middleware_one(app, get_response, **context): # inject a variable into the kwargs of the middleware chain - response = get_response(app, injected="injected_value", **context) + response = get_response(app, injected=to_inject, **context) return response @router.get("/my/path", middlewares=[middleware_one]) - def foo(app_injected: str, router_injected: str, injected: str): + def get_api_route(app_injected: str, router_injected: str, injected: str): # make sure value is injected by middleware_one - assert injected == "injected_value" + assert injected == to_inject assert router_injected == "router_value" assert app_injected == "app_value" - return Response(200, content_types.TEXT_HTML, "foo") - - return {} + return Response(200, content_types.TEXT_HTML, injected) app.include_router(router) # WHEN calling the event handler after applying routes from router object @@ -284,4 +284,4 @@ def foo(app_injected: str, router_injected: str, injected: str): # THEN process event correctly assert result["statusCode"] == 200 assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] - assert result["body"] == "foo" + assert result["body"] == to_inject From 1a20c9ef1b90fdb97592348a50956eccc3ce3a61 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Tue, 15 Aug 2023 23:42:52 +1000 Subject: [PATCH 32/85] fix(debug): fix processed middleware stack frame list, cleanup try/catch in FrameExecution --- .../event_handler/api_gateway.py | 65 +++++++++++-------- 1 file changed, 39 insertions(+), 26 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 10a557111e2..990aee384b4 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -282,16 +282,12 @@ def __call__( handler is executed which may also return a Dict or Tuple response. """ - """ - Check self._middleware_stack_built to ensure the middleware stack is only built once. - This will save CPU execution time when API route is executed multiple times. - """ + # Check self._middleware_stack_built to ensure the middleware stack is only built once. + # This will save CPU execution time when API route is executed multiple times. + # if not self._middleware_stack_built: self._build_middleware_stack(router_middlewares=router_middlewares) - # Keep track of executed middleware - app._append_executed_middleware(self.func.__name__) - # Call the Middleware Wrapped route function handler with the app and route arguments return self.func(app, **route_arguments) @@ -434,6 +430,7 @@ class BaseRouter(ABC): lambda_context: LambdaContext context: dict _router_middlewares: List[Callable] = [] + _processed_stack_frames: List[str] = [] @abstractmethod def route( @@ -642,6 +639,18 @@ def lambda_handler(event, context): """ return self.route(rule, "PATCH", cors, compress, cache_control, middlewares) + def _push_processed_stack_frame(self, frame: str): + """ + Add Current Middleware to the Middleware Stack Frames + The stack frames will be used when excpetions are thrown and Powertools + debug is enabled by developers. + """ + self._processed_stack_frames.append(frame) + + def _reset_processed_stack(self): + """Reset the Processed Stack Frames""" + self._processed_stack_frames = [] + def append_context(self, **additional_context): """Append key=value data as routing context""" self.context.update(**additional_context) @@ -695,7 +704,7 @@ def __name__(self): # noqa: A003 def __str__(self) -> str: """Identify current middleware identity and call chain for debugging purposes.""" middleware_name = self.__name__ - return f"Middleware '{middleware_name}'. Call chain is: {middleware_name} -> {self._next_middleware_name}" + return f"Middleware '{middleware_name}'. Next call chain is: {middleware_name} -> {self._next_middleware_name}" def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]: """ @@ -716,13 +725,12 @@ def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]: is executed which will return one of 3 outputs. """ - logger.debug(f"MiddlewareFrame: {self}") - try: - return self.current_middleware(app, self.next_middleware, **kwargs) - except Exception as error: - # Log the exception and raise it back to the caller - logger.exception(error) - raise error + # Do debug printing and push processed stack frame AFTER calling middleware + # else the stack frame text of `current calling next` is confusing. + logger.debug("MiddlewareFrame: %s", self) + app._push_processed_stack_frame(str(self)) + + return self.current_middleware(app, self.next_middleware, **kwargs) def _registered_api_adapter( @@ -734,8 +742,9 @@ def _registered_api_adapter( Calls the registered API using ONLY the **kwargs provided to ensure the last call in the chain will match the API route function signature. - **IMPORTANT: This middleware ensures the actual API route is called with the correct call signature - and it MUST be the final frame in the middleware stack. + **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 + function accepts `app: BaseRouter` as the first argument - which is the breaking change. Parameters ---------- @@ -753,6 +762,7 @@ def _registered_api_adapter( """ logger.debug(f"Calling API Route Handler: {kwargs}") + return app._to_response(get_response(**kwargs)) @@ -820,7 +830,6 @@ def __init__( self._cors_methods: Set[str] = {"OPTIONS"} self._debug = self._has_debug(debug) self._strip_prefixes = strip_prefixes - self._executed_middlewares: List[str] = [] self.context: Dict = {} # early init as customers might add context before event resolution # Allow for a custom serializer or a concise json serialization @@ -875,6 +884,7 @@ def register_resolver(func: Callable): if cors_enabled: logger.debug(f"Registering method {item.upper()} to Allow Methods in CORS") self._cors_methods.add(item.upper()) + return func return register_resolver @@ -910,10 +920,8 @@ def resolve(self, event, context) -> Dict[str, Any]: response = self._resolve().build(self.current_event, self._cors) self.clear_context() - return response - def _append_executed_middleware(self, name: str): - self._executed_middlewares.append(name) + return response def __call__(self, event, context) -> Any: return self.resolve(event, context) @@ -1052,8 +1060,9 @@ def _not_found(self, method: str) -> ResponseBuilder: def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> ResponseBuilder: """Actually call the matching route with any provided keyword arguments.""" try: - # Reset Executed Middleware (for debugging purposes) - self._executed_middlewares = [] + # Reset Processed stack for Middleware (for debugging purposes) + self._reset_processed_stack() + return ResponseBuilder( self._to_response( route(router_middlewares=self._router_middlewares, app=self, route_arguments=route_arguments), @@ -1061,9 +1070,7 @@ def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> Response route, ) except Exception as exc: - response_builder = self._call_exception_handler(exc, route) - if response_builder: - return response_builder + logger.exception(exc) if self._debug: # If the user has turned on debug mode, @@ -1078,6 +1085,12 @@ def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> Response route, ) + # Moved this to prioritise powertools debug mode + # + response_builder = self._call_exception_handler(exc, route) + if response_builder: + return response_builder + raise def not_found(self, func: Optional[Callable] = None): From 48a94622653b8fce59a7dfccd3f416ed5d1a89d1 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Wed, 16 Aug 2023 09:07:51 +1000 Subject: [PATCH 33/85] fix(debug): revert small change to ensure debug noise reduced via handled exceptions --- aws_lambda_powertools/event_handler/api_gateway.py | 12 +++++------- 1 file changed, 5 insertions(+), 7 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 990aee384b4..7d7318050a3 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -1070,8 +1070,12 @@ def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> Response route, ) except Exception as exc: - logger.exception(exc) + # If exception is handled then return the response builder to reduce noise + response_builder = self._call_exception_handler(exc, route) + if response_builder: + return response_builder + logger.exception(exc) if self._debug: # If the user has turned on debug mode, # we'll let the original exception propagate so @@ -1085,12 +1089,6 @@ def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> Response route, ) - # Moved this to prioritise powertools debug mode - # - response_builder = self._call_exception_handler(exc, route) - if response_builder: - return response_builder - raise def not_found(self, func: Optional[Callable] = None): From 587348ce85eeb9204264562fb30d45d19474d7c0 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Sat, 19 Aug 2023 20:49:36 +1000 Subject: [PATCH 34/85] chore(comments): cleanup middleware execution --- .../event_handler/api_gateway.py | 24 +++++++++---------- 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 7d7318050a3..33ded346420 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -238,7 +238,7 @@ def __init__( cache_control: Optional[str] The cache control header value, example "max-age=3600" middlewares: Optional[List[Callable[..., Any]]] - The list of route middlewares to execute. These are executed in the order they are + The list of route middlewares. These are called in the order they are provided. """ self.method = method.upper() @@ -261,8 +261,8 @@ def __call__( route_arguments: Dict[str, str], ) -> Union[Dict, Tuple, Response]: """Calling the Router class instance will trigger the following actions: - 1. If Route Middleware execution stack has not been built, build it - 2. Execute the Route Middleware execution stack wrapping the original function + 1. If Route Middleware stack has not been built, build it + 2. Call the Route Middleware stack wrapping the original function handler with the app and route arguments. Parameters @@ -270,7 +270,7 @@ def __call__( router_middlewares: List[Callable] The list of Router Middlewares (assigned to ALL routes) app: Callable - The ApiGatewayResolver instance to pass into the middleware execution stack + The ApiGatewayResolver instance to pass into the middleware stack route_arguments: Dict[str, str] The route arguments to pass to the app function (extracted from the Api Gateway Lambda Message structure from AWS) @@ -279,11 +279,11 @@ def __call__( ------- Union[Dict, Tuple, Response] Returns an API Response object in ALL cases, excepting when the original API route - handler is executed which may also return a Dict or Tuple response. + handler is called which may also return a Dict or Tuple response. """ # Check self._middleware_stack_built to ensure the middleware stack is only built once. - # This will save CPU execution time when API route is executed multiple times. + # This will save CPU time when an API route is processed multiple times. # if not self._middleware_stack_built: self._build_middleware_stack(router_middlewares=router_middlewares) @@ -293,20 +293,20 @@ def __call__( def _build_middleware_stack(self, router_middlewares: List[Callable]) -> None: """ - Builds the middleware execution stack for the handler by wrapping each + Builds the middleware stack for the handler by wrapping each handler in an instance of MiddlewareWrapper which is used to contain the state of each middleware step. Middleware is represented by a standard Python Callable construct. Any Middleware - handler wanting to short-circuit the middlware call chain should raise an execution + handler wanting to short-circuit the middlware call chain can raise an exception to force the Python call stack created by the handler call-chain to naturally un-wind. - This becomes a simple concept for Users to understand and reason with - no additional + This becomes a simple concept for developers to understand and reason with - no additional gymanstics other than plain old try ... except. Notes ----- - The Route Middleware execution stack is executed in reverse order. This is so the stack of + The Route Middleware stack is processed in reverse order. This is so the stack of middleware handlers is applied in the order of being added to the handler. """ all_middlewares = router_middlewares + self.middlewares @@ -663,7 +663,7 @@ def clear_context(self): class MiddlewareFrame: """ creates a Middle Stack Wrapper instance to be used as a "Frame" in the overall stack of - middleware functions. Each instance contains the current middleware to be executed and the next + middleware functions. Each instance contains the current middleware and the next middleware function to be called in the stack. In this way the middleware stack is constructed in a recursive fashion, with each middleware @@ -722,7 +722,7 @@ def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]: Union[Dict, Tuple, Response] (tech-debt for backward compatibility). The response type should be a Response object in all cases excepting when the original API route handler - is executed which will return one of 3 outputs. + is called which will return one of 3 outputs. """ # Do debug printing and push processed stack frame AFTER calling middleware From deabb2695e2969833451bf47ac948e9650782b68 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Sun, 20 Aug 2023 17:33:08 +1000 Subject: [PATCH 35/85] feat(docs): Add docs for event_handler middleware --- docs/core/event_handler/api_gateway.md | 65 + docs/diagram_src/.$api-middlewares.drawio.bkp | 935 +++++++++ docs/diagram_src/api-middlewares.drawio | 1763 +++++++++-------- docs/media/how-middleware-works-1.png | Bin 0 -> 179608 bytes docs/media/how-middleware-works-2.png | Bin 0 -> 188403 bytes docs/media/normal-processing.png | Bin 0 -> 173988 bytes docs/media/short-circuit-exception-catch.png | Bin 0 -> 210844 bytes docs/media/short-circuit-exception.png | Bin 0 -> 204383 bytes docs/media/short-circuit-response.png | Bin 0 -> 204443 bytes .../media/unhandled-route-exception-catch.png | Bin 0 -> 202333 bytes docs/media/unhandled-route-exception.png | Bin 0 -> 186374 bytes .../src/all_routes_middleware.py | 32 + .../src/custom_middlewares.py | 30 + .../event_handler_rest/src/middleware_func.py | 16 + .../src/route_middleware.py | 30 + 15 files changed, 2043 insertions(+), 828 deletions(-) create mode 100644 docs/diagram_src/.$api-middlewares.drawio.bkp create mode 100644 docs/media/how-middleware-works-1.png create mode 100644 docs/media/how-middleware-works-2.png create mode 100644 docs/media/normal-processing.png create mode 100644 docs/media/short-circuit-exception-catch.png create mode 100644 docs/media/short-circuit-exception.png create mode 100644 docs/media/short-circuit-response.png create mode 100644 docs/media/unhandled-route-exception-catch.png create mode 100644 docs/media/unhandled-route-exception.png create mode 100644 examples/event_handler_rest/src/all_routes_middleware.py create mode 100644 examples/event_handler_rest/src/custom_middlewares.py create mode 100644 examples/event_handler_rest/src/middleware_func.py create mode 100644 examples/event_handler_rest/src/route_middleware.py diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index dcfa38f6f9a..228c9ee9c03 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -362,6 +362,71 @@ For convenience, these are the default values when using `CORSConfig` to enable | **[max_age](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age){target="_blank" rel="nofollow"}**: `int` | `` | Only for pre-flight requests if you choose to have your function to handle it instead of API Gateway | | **[allow_credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials){target="_blank" rel="nofollow"}**: `bool` | `False` | Only necessary when you need to expose cookies, authorization headers or TLS client certificates. | +### Middleware + + +Often there is a need to handle cross-cutting concerns or to add custom processing in a reusable way, middleware allows you to customize the request/response cycle for your API event handlers. Middleware enables you to add **before** and **after** processing for any API event, enabling you to pre-process the request and return early or to post-process the response to customize the API response. + +???+ info "How Middleware Works" + Middleware functions are composed in a decorator style where each function controls the request/response flow and can make changes before or after the API handler is called. + + ![Image showing how the middleware flow works](/media/how-middleware-works-1.png) + + 1. Powertools API Route handler executes API Route Handler (wrapped in composed middleware). + 2. Middleware function is called + 3. Before processing code + 4. Calls Next Middleware function (or registered API route handler) + 5. If the next function is middleware, it repeats these steps. The API route code runs and returns if it is the route handler. + 6. After the next middleware (or API handler) returns After processing may be run to post-process the response. + 7. The response is returned by the Middleware function to the caller. + +???+ tip "What Middleware is Responsible for" + - They can be chained in a stack, so ensure it does only one thing to maximize re-usability and simplicity. + - Responsible for calling the next middleware function in the stack. + - Can pre-process the Request data, change it or validate it before calling the next middleware function. + - Returning early by throwing an exception or returning a valid response. + - Can process the Response and alter its content depending on the middleware's purpose. + +Middleware can be represented by any valid Python Callable structure so long as the call signature aligns with the following example and the function follows the processing cycle of **before**, **next (get_response)** and **after**. + +=== "middleware_func.py" + ```python hl_lines="2 5 7 11" + def middleware_func(app: BaseRouter, get_response: Callable[..., Any], **context_args) -> Response: + # Do Before processing here + + # Get Next response + result = get_response(app, **context_args) + + # Do After processing here + + + # return the response + return result + ``` + +The **app** parameter can also be a more specific type of Router such as ApiGatewayResolver, APIGatewayHttpResolver, ALBResolver, LambdaFunctionUrlResolver, or VPCLatticeResolver depending on your specific middleware requirements. + +???+ tip + To maximize the re-usability of your middleware functions we recommend using the **BaseRouter** or **Router** classes providing the **current_event** object contains the required fields for your middleware. + +???+ warning "Ensure your middleware calls the Next one in the chain" + The middleware stack processing relies on each middleware function calling the next and also returning the reponse or raising an exception. If you do not pass control to the next middleware function in the chain, your API route handler will never be called. + +=== "route_middleware.py" + ```python hl_lines="9 16" + --8<-- "examples/event_handler_rest/src/route_middleware.py" + ``` + +=== "all_routes_middleware.py" + ```python hl_lines="9 15" + --8<-- "examples/event_handler_rest/src/all_routes_middleware.py" + ``` + +=== "custom_middlewares.py" + ```python hl_lines="12 14 18 21 23" + --8<-- "examples/event_handler_rest/src/custom_middlewares.py" + ``` + ### Fine grained responses You can use the `Response` class to have full control over the response. For example, you might want to add additional headers, cookies, or set a custom Content-type. diff --git a/docs/diagram_src/.$api-middlewares.drawio.bkp b/docs/diagram_src/.$api-middlewares.drawio.bkp new file mode 100644 index 00000000000..93500c7a13a --- /dev/null +++ b/docs/diagram_src/.$api-middlewares.drawio.bkp @@ -0,0 +1,935 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/diagram_src/api-middlewares.drawio b/docs/diagram_src/api-middlewares.drawio index 9011fc8cd2f..69be87f4ed1 100644 --- a/docs/diagram_src/api-middlewares.drawio +++ b/docs/diagram_src/api-middlewares.drawio @@ -1,828 +1,935 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/media/how-middleware-works-1.png b/docs/media/how-middleware-works-1.png new file mode 100644 index 0000000000000000000000000000000000000000..e858d471b1e78ce37eca5002e4a05877633325de GIT binary patch literal 179608 zcmeEP1wd0>8&>R=Pz)>t#XuL7iNGiY32B3Wz+i*1!8S@1YynZkZWQwq8ygV=vAYWc z1v?Q@Q2%qcd$!AVVN=G~(C_C*c6WDo?|JJv?|I+nBs!0_ZPmO}^Lq8_wX(OPxYnzu zmRPS|{ZUODgCmE#wQm6asn2z_wXC<}lFrL|YU4Nati5=l(SZymt)4#FO7NFHi9ly_ zdHQ6EK8a+_r1|qWY!>(v91mp&FajC00Kt1C0*P!$Ff$|$awC!T$ri?@$S?8$V-tdp z;CyNjjfGywkv);YWK#7>HpT-8;8F&TRDTAG$L7-Y$(G=?J&Q+Uf`7qb@Y`t&_~ixu zPbByfjeSk~fIlt5!k9Eqn%^h}54j52bO6}|95xtb=jQ03PqG4kGZ`T?@Q*FcKZK2Z zB!EMW8o*$K(@DeuCIigCAuBqE9STmeArg%S5C#~Vl8pzD%m#sXM2~7iG9Dnf%Q4hI zDu;pjI%E_gX&f#C3<-aL;DwPlXgq3=;Al8ECYlf)YUX6Z4tMc(VhwWl;RuF=7ZXMk zoD)EcWcY(SK|UDBnz&@qJpR6-x-}9Wf;l`2w>8ps2rMM6q^&mH6)5(9ezh>v@M4kMt5Wf z@Wl`iEw~8L)QtZTFqScbBPOOsf^Q1qz`H@uKn{#yOhmt)2yPyEw4ew^0DLy|L>`;X z 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 UM^nHLJ76$d^hxU~OOLp}05VVd2><{9 literal 0 HcmV?d00001 diff --git a/docs/media/normal-processing.png b/docs/media/normal-processing.png new file mode 100644 index 0000000000000000000000000000000000000000..5d1c3cfb9c531ad05c55624c50a06759c5f735e9 GIT binary patch literal 173988 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

rgs}eknUO_R5&lj1%;tkkCG1i;a_qurs!A$(~A9 zy7Ny`@wyi6Ck$x0Dbysg-%E>DBf6=z^r08AS7k&wSS-KHexKEctUkCf(sA+XeX(1! z_RZYedq6-Ai5o$$eZDq1sHAH_p34w36`%F0+VSh=UFtR4xj^mOp@H*ji&q>t zJnlrm`uM|IcW&P)dY4VkeVNmi>7F-UyEA#f*pqA0zou@eadXMfAcoO5QY^euhd8~C zAHnER_4t2x6JEwudz{T1Xm{SI@6J{69h1j-t4U&H7rgC#_8`J-dZ1o6ulKI(xD~}z>>HpHlSF;j?F*^}YX6@p*UrC&@V0B&v zy~AO%EtJw%`Kee0{l42kvXr&eD0dVXl?s{)=~o^yl#B<+fFD5-3G zazX4<+VU;csw0a`9m1=S`D;^HHq2@EN<+5e0$b|IyhliDPCac#y_?w~JX^7U; zISzL}JyVKEvFkyi=j;g|w?hR4xcgnpw&ZXv)8aoTy=}jV4oI~aW7giMZ(HS{?bw`a@;yL45w{RA#RdJim z&d0O*M!U3O*?SgL8oeH4S7{V^_C?NyeIYeZ$FQG%n)*t6sF~}KOC3keduOgQ2Uupp z2Qvb9)M=YLBML|XRNbp4s$}4VOy~!sx?RV9`w-Qt+w$Cz$ z1AK@BNK22fHyoOzk-NSwF8}UW5BG%eF;~~UI8Qoo+jQ}=_a@iq(KqU5ZT4esvGWa` za_7J-<3BEJ$th&UMsZF>r#z4IjB$zE5Z{Hg)zP}!AxrnM;rCCv<+Bgn|95=G^8qK{ zyVbo4wy)iPB42MYMY(M<*#)rqsDb=~@*V$#CZZb9ws^gMc9C7nJ( z$uA4+N95YC$j$DwD)Z~Sr8>Q*(v9Ai71<;xDPMY?@pxF@ zN#fzTIy?2=w+%^qX5~1Fm-FyAouig5nZ&oVZAC~g@=}NmBe`e5PpIzIlnY%b9RwHv= zU!8NySD!7ls@v+ps;D$FE^gO#@Z75P9Yc@hSaj2Iw~3t+8r`pJ{|U3V-k)1-aOrN_ zklh7JcBgxK^fXG2PW3bdIfO-?=9erkUE94#OJCLg-??wbjMUPbx)F%>!Zw!Hz(0N3 z(!C1&oo6(4S4xiBs)`nWzdvS$?3$k z=SQ0lbjt`yF|H^HH;zrd!!FJH%W(PX(aBVw9%FXv0=>09Y!6W z6e{b{sI&)%kB%rcciouX%PV28y4{WoBb@zi($}YrV$JrC3(8#<{ElR$LAvwLmlcKr zKxJL@u18`14b701%MY*Df2^8jz)NiZ&l#jKCs~ZR(*;qX{GS!e+mzkh7k$RC?H-js zdg~qN<9;kQW81otmhawK&`H^223rCIT0j28OV_n%f8MZFf6}gtMPG~e#pMOdhf0&Z*$yKqpUZjRoKoHbQxDmyxy_%uYKxO zEA^HgJlOtWSy|hNh&sY6>-D3%yJpU3%o_5+Vf@HXcU;<;TvqD&WsjbT!?g07TWhX8 z8Qk;Bd+(=CJ3SUDB}J^>+43f@^uz!t%iSZ(hj%+cej9M->c(_`twh}gtIk&IbqF}% zvAfG~qgB10Urm`rqUEe`U2sAfL3g%5rS&KA{o>4d1?hL4IE`DZ6Z|`wnuSb5^7qB`JC@A7y`Vb+Ft*>e8P~{ojUh zj>L%9!v{?anP5pTv$45+Jt;6;#bU$%7M@wKcI-@ZP!zHPRPH>=dy#fMDe?aBl8dKL z59=Np7W(+)gL{YOz8*e)PU>Xa@WMeuTvzi-X_mCepTA{p@cqrpUgyQBI=1EX&9m*i z*JWQzHP?UtuAO9YGx)GiK~Pn(Tj1-zEc&WFN`9>5ey+x92B|W|cIVk`+rO@TxqxMN zcHgX19m=jBX#e7RqF%+~wt<_k1$|_e?)X z0wop3D}d1q+wphp*>{zu<$r;woqxsaDa?B(THn~~sQ-Ax${Bx84cIhh%5kHdn1~3& z;Wa_`!k*@A=o#5({Fx;I>y%6S=0AE=f*8@E*1+~(Y#(&-6eDEo9nXS9N?m5_=Y>bp zz3*oio|}Gj7Hx!C?6ic?m}x7Kw3=p(+O?Xv@op;?E$#5|&Na`F_s_fc7-hXbb6g!m zC#wI)qh*~E^`1ozH|n_EB|Z^^iA!oUy&V?s+c)m=)++sdrM|@ATFZY&nJ?KDy~)sc z{I1Izmpn2wp;Yct?WY}ZWYgd)|LT*uFAM*$+N|jic(S@cb^eXxC&Stkz4QL8>M=a9 z%s%96P3OJ#`?ufiUZZ<6uC?W6o%Ti5r`}$k#5#BDW2^l6oy@k>_za}$n13j*pnN`< zzsD|FS8dLTPTJbqpImhpM-R-ru&vgRQJOp>^17ST*GrWFU;ZY(xje^-kp_@?KP`8H z+eoA2*HIQTA}Cd!hZx0&2j30$>X^R7&*|9Hft#xPT~Sg8afP|ofB>aYkqn>SuAc72 zF`s7~aa#MZaO1g)5sL~!mDYd$dq1hNKbih#B3;kRG(w|#M|a>BD1lDx#jU!j z55kVF)%Mh<75UuUyLxfEF55wk)tWJN%exFZ1M1QO%I?o7udQwO<#A7&;HxJy|wkNlOaptj(cW7>6MZ~s*7-LmiupRM3^;=c78snV$_nz51dt{c~Y~TJt zPbAnosDHHat4llgoIX_3Q|+Ar=jCOqPkZfxEfaLR=f)odpQpci%LW>`6x1@Yif(UA zr9TQBIV=5BkI1;ocFBvw!^1yO>eMu6skPMs^<5QThE#92&ac@U-7e=^Wz~_dkzjR zT0pl>idLI5DP?lZ5Z$xOjm*K_$C6S`Pj$MMbn@gRkXeoVsF%GOxOLk=rIUlr@@)xM zdycL0oD4=&z5<4N0%B*p;O%=ads z+~Y=RB;dqzYtLQWqc`Q!VGR)0ZjFSs7YLD9AB9`Qbp}J`=a{ zyT@G)RIRV7%F52znb5UD*H$g`-P5w7e_T)5=C+DDzqWeg%yCumMlZCE)P{d~F)y3@ zd9_>kPEcjEl5TF3#M356YF2H~J9kkfcig|ESGA9CaPFt++ju)z*a7L$rhb}gzxRtX zK|OT)`_lY@RfE>61jVf^INh(C3ZhcFJp+EmlgVvX&-`n}#GYg9cAejK;HCXyYR?l% z5t;NGc?Fv$4OX$}WAZs@>y517v{GxkNy8k!92s!_c|~n_*JYh+2XOjco>u#%h?4hZ z@6lY43sIk?$y(m-qte_L+8sBfs5zFB=ik|`dg9}k4%)0DgX33wU*|?R|D$daXq7mj zH;4n6q+C^*ab#}$qr(y{b0d0wGCokTp79}$uDj#&lD?XosyE&sSM~jylS|EbKa0R3 zu2!1V{mYH2m$%-68q(Vd(Z*(ok{Gpl{XwTwmV^J$@~Ij0zWl))-$kC|<98&i(rt;n z-FMUL>d4)P+^fePOo-9F^VS@wg^{CxT6otY;Xv5-Nj02^66BCGp`X?I5`92yrm6Sr7`uF#6QF_}l;77MhInUpcwn?Bxp^5OBH1$% zu8ss-(#o)z6bZ2$p6%lwpGJbpDg_ZJ7`#wJ70VAzeM220eR1K^Kl%GVg%3I zQ5s&XcK9NdoO1Ioar$4wb`jS*0MYWNV{L?ZI>ulBzoX^xlKIiVWD}l0&%<10|MZuX zL-1!Qhxs5YyMA?U&T9^#JJBA+FZmfrAoGq} zN=gdX{z7-sBa|ICgA<@Qf|WTRj-!>26MUB_;Ws_uE?#QAkuP8@bU&-RaQ|F21oG-_ zXoDQ-rpx-()jJ(z{QP!rE0kc4_rD%(?J2?>K}sUx+6xlAMFoGlW2FlZ63Yz7+|d|+ zv`wk1m?r&5zl~%W@_|9ZZ?e~0*?xa3f-eH}TE0l;-MFPV#Sna3OS9_4KoQ!>3`Ev& zU7YyAeq{}eU?8GX8DEI>@8@r)H2VXIm%#p!B7RWh)-9Kn;xW^vdw-U^uD^Xa*Q%L4 z8Zt*Z&A3Uv{x~E(=}sXU#pQDmfi&v zE50;*;7|7-=l#y9-_)0|Cq+#&phV-uj#eB5jXnzls=E^P%y>Qa{Dp?t#e-< zWf%b5s}E%oxiaD<-AP-f<>@Pe{6FVxCm%Xr2>V$N|1~-;>KZ`84Ec^NOWD@1_2e*j zCnnz~=c)a+ zm!>Rq;0&){7(U?81h2F4pEo>~uVbbr0gQf|6n%?9wcR-FV&xtPU8dizJ+dn9@YI|I zK)}RiKb5&2g=_qSo|iX-&Vh?=82+3#kS|U%`zi|c?Jkb-Yj$}1oASJo$2Q!a?)BSs zaoq7=S`6Pm0%X1S`nk{yn4=8aV@|^*T<6E_as{-$DrVfBeq7hnN*Xg{*H`+{iX1SD zqx$EUtYPQoczm=v>U2%e$U{Jjl(>lUX#3(<`IwKMqST?__q{*;3u??z`X<;Vw-YJU z0VFh(6!CU8R@1>wtdW3-HLtb~k6%^yzsTz^UMQNtj0>GVs8hU~p8x_jh1I7AY0;benMd{E2mc>3CH5kGA^#A6l2jLh17*1Ej z4Dl{T6cjV1_LXQMGrBM!eUJLWm#2FQ2ts(l&yD9rFx%A9O18Oe${%@rjB3?so9i-{ z1dG;8-VQamUI9#g(ed+}y=`|6&0I^TS@t1kGw+CuOjQFDbSgr_I9DtQX&;MidL1~! z5YY5D1OB^t`!k@sXoi~A#=QIPJ%_k!wNDK?M-AEg8U~@h*bB7xJc5|zA7Lm%Pl0I(Vv&mN z+9aQ_#92qbH8}B^2I^U6 zeaWZxx0bxY_yWVa+!wAn;4Q?G+akaO$K9FlQB)cI>?I~Bg=o=FRQyMe<6^OWMPHYJ z7x)bHj_lXz%7llThmFclt4!Dc)cj)7X8gJDDhCH30UV1y)%8Y1qKpvOi2zUy|5*&s z(#C-`xE^{3>KC^|lbaDb=dAD?q+BhXmgB|T18!6Xq6&V8poZXEZt&ZL;$FHH$w-wI z{{wE=_99|0VFPAZ#&6n1hJSkdQN5$w>*I;1l`)E};o^sN9z=baZaXW2$G%ZE<}MKw z3N;$c^evw&j0pP7D0P`pE|LsHObtuOoVyNFJiK*~H(Q*&sT#!D+1dB(`p;xVmb{0< z;q5E9Qf-Ptv%d3e)r95h&QicqJc|6er6~O>6C}_%*KO>q@|6r!pbf0pAnaO{=&K!S z44W^S{p*|t3*uiL`Kvh8x3%^jAW!C87n+5M7~IR(Z#}y<@_sS~qU&LBlmoZ;Vz?{1 zs0m<}qNj-${8iGFZdi7_U3^*!W{W1l5YSyjNU?l?r02 z%~SSLaROs)=InFx6hOm#=znhaU!|=}&DLDfC3&<$xxJh|*}~iU`DSZ{NtQFHCmz>T zc`Q259}kZ4p+m`?F`GB9a%g`vRyIgi-29L{=;Y|&nb!JoHe-GJ!(Eds>=}VEiR)`5 zs46HN(UTIQ)8`jV``TKqVXekHUj8f1)6EKR<#6+P42o3-sxz&s-`G!&Tj=;- zf9F|`oO`P?OD(_+$nFBs)X&6_T}RON+#QwD6Z^X~W>&xb!!-#5C$H5b_&MlsjOguMRiM+L!O?yTkyBRwhGbMZDJDInX6DrGRQm%;Bwh8n+0d@X6ntUXdNs{h}7IoEe z8o_cBFdKXR1q!i8-OK^k7C+#NQ58+I>o?QLbyen+d;D zEAhH@Tjgu>y9<~~kQmJ5UAt>Wrk11aQ$(e91B?Thl*5;^aT<*ZeM7s23*G7ahnr|# zeUyHIsPPLh=-EpKE0fPat*lQR;eR{r#^v-yI|5;5Ku^KytVUb3*ek~2aWV6EEI`VR z&I*g6XIrQzbdkYx?5Z+dkilYmGTE!w7=QU1(}{_s6Drqs2yo*PceSm<44EW4&S$6c zqHY&Q6FSzuY-#|EP`N`~C6XKquFks+{Mv2F<8sJvpMOODHM8sS4DR{2qnA%x%18&? zIOP{3nA#8brxUteD*2Xxh`tA@-+l-NlQOJO01|&GhMPkfm7`tu(Lhe~ly1eVfCry> z_wy%52f9de?Qra0W#Z(`g_&{Z=lKbu_|5Nw+TPP5i?YZ~j-G>A=lv+$h!PO?p;ni$ zJDQ%y;QrQPVv~>6jNg$7##GUewHN2!P6#`oXKU93#GjO?;a9XoT(<(a;@;a_%5*&j zCS$8%*9tan20D~Jdxd>y^t6SB1|`}&vZm|l!zOiuTv%uNy=_69UM=mg0^Y(~w2Hg;`Z=}8n>(^lt!H0l z!mef@bHoOf;)Vi8tsUyPx0JfpWnE;W((n!fhj)!a>Y=`S&-(!(S&+W)FmtzT_Qrf+SRiV{SIPfWh zr9XUUBb{E}M&4Rm@odN(SnS%g)1C=5C~#Z#Q^qgk=$tW^@HGVlb)42bcxzf z{x-9)Yey$*7T+CR!>!0@N5@i&!r^KR`|p;VY8b9h^f4NV*vT?R-X3lX4qz=zOF7z7 zk-{p%oR1c;o(UP&4-H}w@c9JlO+n|Q#`Ee>u=0T3f~a%^4ud?g^(GPdNK?}H=2J!M z{Ly>XxzC&MD<}OFH*WQIa~|IZdYWMByA|jd(LYim|2Fe+F){Xr{^pmi9VKks#CpgH z##bky=CbZmTF|MbZH{%LB=VN?&TqTRMmf{H&vch;*0-Oz&#;_-71nRZ@p`t2N*@KG z*d#b`#$Pvwe@#_myneaQ=>xxejp3=0b!_L$Z^-St?1vb^v%xnwo})S%+B;y6#@z0; z=!FAepQ@_*^$|E10p zJ*(^dIsfLfF>FsFzh*ZD8jHEV1>M4_llGVkw2v{wpF7f=_lB=l*ZNnVoY&x13_r*g zobbPZjy)5F;b1MFMo+D-r{Xy8<$Ri7+a{_ZnZxHyG=I*RO1c$;=$-ktn{66y+BC!D zxZJiV)qFsa3L*CBjXN!T;`d?|$aoQL`#q)<#|c-1As%%E@`I=Zig!ZeHsw&8Oz8A< z&@|SXh;wzA{Mx~z=QEhayB3hMl&^DCIIqj=IQhb8D~b5fn1a%D-gT~_qeb3cLf4um zvb{GQ+@%#|9-L^eCPs1hJK5hh^*hVvHaEo{FRCBT_%j36ZGVaoBBhQX!Ekx+`;3j- zy;M&;N`-&pxg0dE4C~dEUGzZ$xCFg>_>CG~H04Vgm-b4yy5b0;6j_U&xumygUUZ=V&CDfD&$K zy(T!?q1fhJ9udLgN>O};EnxB{Uw<`?9%=x}t$-c8S`q$D-#9rHB8q$d;Ke1KpnaK> z;GbGHm2}6zlzGw*-4;7L2n{SgqEA|=@E-fF#tU=6L7G+|JtPZw!|-OU%7lR9TPv!^b-~%=#emYt!H6+PwH#=)&gOhA+4A#IoNC z=phz`RW@zI>LCxE$&>SC5ZIfdxqhK%w!v<6b2mW#KaMuO0DuL_}>Eo5~qxGcZ&8Y3`yE50Y|3wvDyuQ0D0SW+} zxvyOq6=KiBa9EN^9wSc}u8L-LjxLPN7fflV9dbY`YfA5us#eX;iqAU^oj)n|9?_Dh z7DGATTb&`&C>y}PmFoPGX)M)Rc9qHEEazQqqDTyVO}xY-2JVes-7UhP%m?%+2S!}$+d##Sf(i-qA+vOd7f<0( zEKsv?9!zH7GHClyTYq{2?3x+KGf&~#0|1h`*;e&j;1;(Qd+=##y`O+~+@~l`%03g7 zT7XLl5VSGjG3h=bN69CVN8*!Cexkx|r51y(p6|+Fm5&kj1@o=Xkg+RI%U=pu;G868 z1)S#zoBU&5Zlgs-&P?nrh_9p3VAiPMN!4RjvO6j#`dE=oUUXN^DI#25P7k(;akaF1 z_Zlm`7?~%s4e?oO3r*ZCjy@7pX<9S_YS94JB{n?4T-dt#uSdr~z?b<83763!xIMW($45pH@YxJI#(xg+y;09Jtt!{U#$+71B_ zNH1C!4zT*d_Uk8XOnTMFsi@|+7rV$wnS2|;L}FjBUF(b!=2K*#Wdz9n`grHs;@poX zlXOQb?C7eTwi-b%J<}ChAdyX^r{Afk5CdBgL@4=cZOR}2* zPy{RvsvS$X5EW-2&0%e@D%%hmfxIq>UFgLBYrEt>JrMgs_sa`gW!98*S8l&gQHUFC zs2hrOXnhL?A_Hg7{hpV!?EJcNiHGd=6Y2w!6~(499ChZEnE3jo&)- z+YbBZ7e4c9UEPa@pBQ{}H1%F4RV#!O|KA-Rv*Cm^XZf zjTv*C)}4gg`8AtK@8o=OFeZV})qyne#hdPxFF$a2gHD8GR2lbu?i_M0iCc2mg-70q zKU+X?5!)$9uH$aR2Lyq3cX9_==~mSHr}_2*u0wV;OjmazG3k97&;FT;+`=eowEfn7 z&$zlWF*}>|7^$CF(V=VeP;{-*sIQWSb_8}JEitn;?w($Hc|VwUm;h^Kp5{45aA6YR zw1(U0O?}p>OazhHcsVKl0m=OgKDJ)L13U+xDYTfr` zGr1JE9g`7i`}q|K&iw2CElN)7v&ezd!1@ZMJ>$-kxHu833%*o5 z$_^!F!(WnTWCE?0wRp^rixBI-t<1W8F3UQi7jf#Xh~QFn4v!t3Xbn+hI4);imk8v8GShO(pL6#BQO z38*RpomnXQblg3e;y$U5vYPw;UP`$+5ukDIw%kz9j+P7&ymCC|9LAyRSsG@h!c5gI z;dGsjY@7h1TuQ}X*#r$jm>Sop|@L&HmMiXfagS2|5>)P z;h23g3#upQ!hlHwz??iAkM7<$XzCAR{7+S?HGuL3%7osD zXjfjD=H`ibj+^;T+7`|yG^Y0q@M-4X@yY!ecihdTilo4 z@*Z}dj&Ig3S@yUf*3%Y46zNbkAo#!-1j5oFw*R9h+m;Eb3O(*7ia9fZiteep%(9+b z*!amz-HN-S+}^n>+myYJ2H)s+rnw;PzkdMQmHRKX>({b(f<%r*s!k%*+2FF?FnqL} z7SvE1L7Q{>Cc|<6!vfVo&|V2OqlpJ?W%8S%xIe4T2K{l+*5e)zy(lT69_m!XW{6C# z>*#5-;d};BtGuC|W5gE}i|ERfYPE0m1eA6DOUmlP9U>mEC!%@N`@Ip`nZ+(kesU%% z(9jzV$m2Jh`Im2~*H&5cxd_dy5Zwd}^fY(WMRUupbc&BxS*b0NEmWMKaD5;Z{u5I) z$G#FeL}zhZ_qyVcx@7o`6YNrW6H`a0U%9*!Bey9pmS%TnuUR4>+){AkM~tlR$5TN^ zq(8VF5M6qO94)(^XR{Icdn=~EB?OUvya#E6@-vU9PI=)#nN!qI?Gb3wZbY5|<+e$F zE5o-2P>y21Cjgk?b2;uW?Q!lUg&h43)giVJ$YuC09&Lo~iSO8e&PHOXz|!l3TG{LC zuijNS;gy!1!cI?3;gOTmb3QpDdMH*ywe1hbQB~U0x-paJP7fBGs62cA1Z~B1BOR^% zQPdf{)vghtFq0`e)67VR`#0t~3|m950AQovxW@_E2)>hWtgQ$%mX%I$4+tujy6u0f zPsDVX?e@v$yDx~ zfgZ&YD6lg&E=gDnA?Hp>(z6qJn4*%D{?b!>tjF0FL8g-NGZ&U=66F|NC2+1Znl^XgzN%zl2C+LE?(x+`sF z9X@$!dUuvslAek1q0uiU&Nm8~0F8MJkQR5DRxKAzQJ_N%@J)|LHHlv>OzA5ld5c+^ zL1V%AXN1@TLPWgOH<~5Gmx;UeWk2z(G5Qre9;x1@E;(}bQ&+e=(bYAxj$>V2yli;U z{)HFQ#rTM@(7p^^a$O$Fgnl20%YIutm8rsP5R+WO4)LDBpme5gNmp!wd`uY7t@X&C z2y*jnHmboYRn+y7v9n^yW>NuMNe++e*G663so;=DHRAljd$->Y-ShV*pmrDgY5=9| z0#M?YV4sm-;nEbL`NvSfjtB@o9P3C!+9c-}x+Kv02q=)x*PqyDt54mxr6F&fcA6y* zY`MN7q8kcBjt=|{_jWr-_jG0ayv|g~YAL9FA~=u77vb<-*tPpwCJz+BrjvWhZO%TXp?Rai*>d?X<+z3 zVgD!A9@J)o93c0nZjgMwp2gg4@T#(CK0owmP0Q8ZmE~sa9wRS@QU4t%X>My9mFL)6 zK%BB)XX}T`lrUyrX95Tju(Pq`Kl_U4q;Zzri?kZC)7X(%$-su!$T*18&RMwjX1&ii z>2z&18Oozwv(XgKHp(IXrt<3X7E$QvfnZ~@eg5DmXhE&-ZIH@m`OnPNba;%R>wd<= z9P7o!-Or3GR5M#UpF*vsrpw<0K*JR}h;T*33A>V%k4uZ|M~oNWiUou5^80*^tUAeL zVAIxeXLJAe4J*(VYXDB9bTEb(a>16#%#G~+)t_jHL3X#X$@u-vLiRoSoRl(_tHebZ z%v(Cz@v{vvmOT&a`|OD>f1t%vGxHSZpGHedY2Nl#T55~&%Y7ZYB_tcF~`~^*vBzqXrsxGI@FOh!SpX}oL$?aZi2^v?Y ztlydPa(=HQ*l1u^+#M{p;fxq*p6-biF78k>Y9nVLNa$;$;=QAl{fROujAl(eOZy$@ zoi|C&nwJ@Y-udwcmm=k=Pfcs%b~T~T+ej|}^wHK=y`SASyHJY-R;h~C1=AGWzo0wr z3ly(z&K}t3&e9N!SotsNKlKA^VF5Uc-$VtVzrHb9{T=+3sH&%Rc8+7h_qamyIBW5q z)&8fU=ryovu9!?eR+2E6JD&N{PvrTkUDCM49tT(DoV#5&vtNaD!$yoH7E6sg+{Y_H zR+BdKPOeO|x?kf(pYHt&+Ko~2^NBM%bPWLv&94?4(u@RBpdH>EN|}Vx!Fz=IEul?7 z_;O9>b_a@W&bY#lB%FQCKNUuShHB6BYo!rN~S7*gyGHJIsW7g$C8*VhAu zXlWUJN)-XF%``LIL8c-9pekBH_rK!;(`@VEpyqRUc({IuIj7$?drEAofp&ds>tT9t z8hu5Vp({Ukz9GUhy6nx3gM+n6urUQBxTS&|u@ybd(WxMye_{HQ=X(w>)M`!O5cQ0tvt*aSJ`(A5J_2)Wih=t+g5m&Mx!jfw!G<=jUYQZbSko~++;5Y5 zzT3o9JvqnT*VWq(oOie;D2lbCKdfbU_;Gzg zRGq2YMfsOH&KU*g=xIFhORFg0y@I#8VZUN@vc<pHhboSo%Vi2!^ zWam3&$=v>ygJ1tqXvyY_8fLBfyJ+>-y9;sQu*#tF&|q_17xh=!K-w7oxf*4hgd!dn ze3foscS$Kzlzj81crg3viG2=*b%Y+ju;>CspG+<_(ZItR6$8nkV!Lj6lCP^mX zm~wv-f#-*F#Guf_-=MedR#sjfv?*|~$(ddrA5VOmOnGl-j;ReYCg2faStW`;Mo_I5 zcctU$l^B^jb(sw2>+_8(gzbmE5@DRSx+@dqD)w+TN^)v%MW>9(p(^Fnpb`$2xn%+* z!7*kh&8xa*Z5NUFV&jyF3an0HTV+uG=G7YkT9@rhZ`L2A`Ao_^JHfa2NsZx<%}4gZ zh8;u#FN|PsdyGPrX`&q_VIXmOsw*+9)D|VMYBmvp4#=C@btI70N10QE@JF_GIaJk1 z6!8d=D&8bl>G(+$+338$!)E#ASv-&A=bA=TltT)u|7wzY`Xvk>U5A(>Vz*0Ac?ZDe zlE>fc6kU`c7S*=k^}2 zFlo}`DB_6EkkOQRHOEs&AYONJg}OOn&eV_g;nTpeC*Fw;`Z2CT=W#kxsCKf>M}e<>vv7VHXrgVw zn^fGg_SeK|nF!HPOYV3|TqXMkc5b8o*LyzLK?oJ>WN?g>2#(E1I(S3iG4Q3+#E|sI zFPN<>`O2%X{LF9;ef>uDv4Z^k;Fyp^bv5D3ur&8E?E1$q7WAL}J6UF6p5IkQVB7!UT+ z?8~_(#A*pK8ZMx(akw_@8rl1`U{!v3WlLr(vwzd;T;ak>^$Nc?8~tZScltW#R#i;s zMfglDigTQAqJ&^K@U>i4d~60<%69bDi*U|~*HKkx6fPe*5Q@_pU|Jb-N+O>4!k}S$ zN9eux%W-xFE9w$@uKm^R9G(@9P{jxF)$^UwzM@~H^o4AMKNkzvi#kmrRB#(ssJOw| zR>}c8kB%6TeBQPa7lY~*jY4u%iK~Gts^OeX9W8ldNw)-IRH9@HHs}6*gFWSf(BpC8 z`3o-C>erDr^E!)2C%5VYB>ohn!lLOxR!-IcQ``8PZlV1zCIQ(li!vLw_y_0JH6{o4 z%5V=wSs^1|c4OO=W`neRg?{jUyPp3=HnRmC~JX~-7uI%XrV62kzC zeSl|7$K(fp6loi~)otD#Z6zuYWC>@^(z-rs`)tY(Spm1+vgu|Zm!WDU&EaQx00cmJ z*!a#7MKQD5N7!Ci_}#QoO58d}(c||eCB^QdnmQ8VE(@RD_zvfkeDo1I+N@ypbI`;H zxM<j=|3jP;Z$5R2~OB`@9%=| zr)o)q(n=pXxBad2s3SHd${&$Y#4tw6VAWo?+4 zbenTHYbn6(N}7V@`)*3Kd0S%q$Fy~apCo?trE36e=@%7T758yXk|4*ah0$z3b@p-H z@^)=LN@te$*7XegW;osCSS0|9=^xPum82McKz|+21LN^3?{(OD(jdfVKBRPCYf=;w zAAh`gI9SkQy|0^8r`MeRQwek-4HrZ(84 z@;RP`UZ<}DhB6$ZM^fQ%Ed7F0pOSdiR_~Q=kD#Q<0~zGX9b#$@mxZ1h@=!(cI=X&(&&C6Z!qUteA6GM-3vwwIsDBY(BvEya*pSRWr<@axWi1} zyoJahH?G*Mu_eZ(I62f(W})U5%Iy*>_Ld3JIwNkfLe62tq>%Qo4lR1(XnJhr(|uF| zYIu2W^j6H4#KO+IBz*;bU3c7?66YlQf^nrcnZh+4WJ_`9&LUoh(=3?|0)3qMB%#8M?i6@Zvprt;GDF+ok zt7XY56KRWJsqN82ixFK!;hW2*wk~$-CE#8y46n&p0=(ZEk{XqG0#@^Wc*=2Gp}Q(Y z=2TL5Mc*s^v9(+3C>PJ=co!hzI}~}3sPJ@Xfoq(H9|VwLD@Qixz8=7D zxV#A1+RlegXo)l7*?Fc0{MHD$6!|AiL&G zm#yrr*3n4a$T0Qrow$@2;p<1Fb^j@alW|k@bf@-LT)H>-4ixd37P=QmmiAMssd2(O zt#gO?u#E3QG)Y#5{#%iUueXEsB$l+!VC4`HyFCLJWQEKu;c zI?N>F#u;~~j8-#jM=v2U`rv%vW9os!9;=Ww+st(PU=<9sxmd1C?K~;1Bv69i+3<^H z)K%EElu(~l#tNb1`jZrIIxTcF;Hu@qaZUG2OmpHTY^B5D^SKqgUtfJPXdfLWz2$A< zYA8x%6wD|KzLPUQR_Ed}XTWvyg@t;LVWva$-|g=4=}Q@#EARKN4kdB7@LIsfSlCxr zc*T??>JQ(0jiqh8Bl$FLw{^cyYyUgMPZgSjr*lviwq3V*rV#gyG$iScNXeEc)^@C9 z%ErYthi>sho?&`g+U;x#WkKF*u5rFL5?0Eba~Ci{r^$kiU$_*xLU0w4CCeN`b`7#F zuQ&BKED;LS&L65B5gj{akA+e*Gy4MPOjShs5dwN35*KBIdBI&+>I|jc zu@urTqjfyEnl+kx=K@+?#5I3R8*5$n$yOzIrrm@MRw@=Xwu8IDsPFS!V$|=1UiENM zp_Rf1y}Ie)ATJ_+YCV=KAc{}?w)>~&htKTIp3m%=ptusrlf_s@Q<%2+&3xyDbn?9E znUVDSE)wZda<8`&`VhsQm}2(>KV|hrlp&%oEyy)>o`dk{U@gwO1Y+MiXR}j{w7i7U zeY)f3H@1Q^v$}v_t5TO~(d}GN=0IxLkrW~FRxVua$mv`ZxM^|=A+z8*NI@`knZ9jW z`~kr=rpt9j?M*=aj(yPI)Q|4yCc?5aqLo*FkzU`>@FqOyf+#m^P|@E+65dt5?~O41 zK19ClgQ)tdx-@1^j1GhFDf_g>`6Ih7qx=VEWr;X2)Zts$Mtc;ysZo%2>0zB)C!5UR29!F78C zX}y)L+e74}O$OJ17b0?ly)fzNnrs?R5_t>GFq6be6I#20x5ocGFhdGtIhOcGY|Oz` z_fa}Nd-vFXDeO=_ffX&Z7lSE=$k{FLS&r(9z(v?|~F_axjA!?IUj?T_vNuaWL^R*6ohI}hRr=t@l zS8*e$WDtI^kTa8NKH#q6hGH&vhBHBRF-$7yvt=VQN5wi@dzSUlBl4!rsPXg>L03J z9nVV@%9NYlz~?gCSft6FqC#xy02RIa#w_L*@LCBCj(agh%M{%J1pP!h4`+f4U?X(uR*)vn{5w2Aw#7lHWecDbvv3>y|a zURxYBSanMZ+1Ks*<#uxoRDH*EpQeES(@e(SVrXhY-iMP;Tc!?rvEBno2MGEt<^Q{+E82{$ z%Td~^Br(acZv1l0E7$iebnI%Qn}-&Tp3!PX1cc~#8^-l*PFZ{6=i%%Bsm#BW5s*qE z^SynPMNZYyXD+LiFlj30Nv&0vOPQ{sN@kT`P&q9Sf=fx<%9CR~=}Dw;`bX5T^*Jz@ zs5rjVA977*=gp8uKojB;wGNE(7DG3#J#hSB75w3Z9xch`8yAU5orUpCE$Aj!zMN5? zjvIGAl!?6#EK7FMWn7@)2iW(5dPtnku*iAA*S?;sp&2ocx1?75xa}=jLoIr}d=`s5 z4QIJaeIm-N>zoaCvRc)u@+U6Dyxv~Wu|1T9tgjhh74>-y4fc(#2lqD+;{Lw|(|;N= zQ>_?frJTTsjKb!xO0%=u(xZOd)(XEw`gKL=d#x9FRb~w4HFB3_Z;FK@dOK{o$|;zH z*MB6T#o6qlrP7TRNaI6BR~eVCIu@6$$FVH9Q$D?#O=E%&fSO&BHtUfF<|@ej2O=@P zlYR!K7h+2pl#{O~vP-cMLf3252t^8Ze|^l7 zs>SGTLE`W-X;P-(RE4-$J10z&@3tel{j3YwC=|}evF$d z%2VT?B4#Pkhh;Khp=+p@D&~>f|a$qlXW&bO$(UuH=7>J-(u{ zU`zt~W%#-nm#qD9b?Wb;3Idda!o`zuX)2Qgj&ji>R2Fl!F!Xh;A;^i_`v*qP3FSLHwkX)!wn;zARWx0t3JzE@ z>>Bk4hWuc=P#FQ7c75xQ&PnW3{K7#U*vFRBDWN`t%rd+2%}(WXvCKK3HJY4uaqocg zRRPBQ^D2OzFi9KhR+qSVUrIg2Pjg{K4P<1N^`OZ(TX7?I9{`eQow97XKDnW~6ZYPr5nNvH~!fv$)bc%iv1!JCHQ zK)oNm5R#(Lp`Jg@Xw9aD_DRar(J4yd%#!_`l|$AkD!yLR?M+S9>arwlgZKiF4FFc7bimFUBv&+uWPEo}KgiL4gz-xMZGKjXQ>O%2s5@marvzGBTh-*{(GU#{jh2?c$jAg(WN&BZ zHJq|KGF6U>s<7ImfX~A0iHq{PLUx6yP*esg#(7LWF5BQubm2w%wv5Nv1|EKSxu1-_GP#E z>b^ui=}>63QN`V}m;=Fro#?cM4S^?7PRx%S!-GuG{p9j~eGzL>caa9#yyOmMvG6tL zrqM;h^Q2IrAF0dxr*h#Wd90bYM}ZnFFvU(bgS?#b+m8gS!KBXlgN~lu0+U#{0{_N& z2ram{*pDuLU5ykazI@hHnjc7Sxwqlo1~4k8e`Hk7z?3M!&nZ*=^t1w`X`;Xbf)aEsCr9apL2#hr;Vtx892vdF}^W@KY z^+X%8bCazB?^B}eJ?TKqYD)j3K<#1%*syNPFk zqCmQd*BDgH$MCo+LFeQ2Kg+^X_p>`rH^? z!k-NjlS~Yex2t-iksB-|C|gLp(e+*BPRHto`YgkRy}2|n*Y@{B@t;zIyi)%V6iY_m zY{Fl>SyQb{po2JCvo=P_Yk#%t??7_I3d=FCzRvTb!pX&OJ3Y(|9;RX{zOcc@T&IdL zxcslbqhXH8Rf2idH6YdjR(xRuL*}v_t7u}B*>haG5ox)AL^V0KYw<}O_=R5@x6sun zP#Sl5_QtvKXzMma*;QUQ#8NvuBW|x!EeED~s$r8)HhU;F7 zLSBd0t2JSW4E6a^qVeuk@e6%fh`1d6kenq$2}qiLh~>OD40oT~7A{scShc-<(6o?H zzv^d-M7n%EGghib0>>^D+UPIoP4zqwR-Y{~KX>Gi{=ejif)v$5>^W^7C$+qhaX2t$7n;&Dh>5H#G8 z?_7QdPHO&mNd|D?fYzG zZFMo1`&LWI?W3^MMe*4tUV2B&xD5qjj>ud&d<*;i^E3iGcZhFOCu&&j$~(R5Zs%BG z9{7GnmLGDsG~;P7u)2XTeOiuj$RN%U96j7SI)^x^R`>!G(w67bfPob$LQBQkm3w*5 zw>b4B_wCOK!Tr^vqheB&nRF7)fEreTZk03m&I5_Iu5VK!JWI8x8rsq45Qmh+skv3S zO(%^GC8~_;^H*n`SNdmhforOEnKK87B^FR3c3r6C_E>}D=&GcI0W(xpDWG|e;OzzU zbgfer=~xOGIqYLLmH%oV8}{F8(p58XKFl=!)xu`N&=aNOHc zh~(V67*o-w(C(r?q$=nf#?cJAKi@~KWY+rD=3weVBm>G}v=}>ciy>;{q0v6W2HZ!q z%L;8*{YK+(s`9TTU!jecW67hV7XHpOEtLVPfQ5E#^en~&GvzS#~)|ft0$ihyic~4Cr+q?+ok5ZGX1tWBl3z-JT z%Wih^mz=~2)BHmZRm4x=fhCGTumJbPOGCp{Ouk68HK`l1yF7nra)`c${5ZS5%H)DF4hH1!ie;&5GMLszRQg?z%@LPL->1wBXo*<}W6bmOQ;Hb_1 z2>h5_e!YiX@2WEB1atiFyEJl676DYi?=1W?t37U*_g!=o3kO22w{vqq6?oGuy&nX5 z|D^fa4}$kU-w3?R6%blb{wTEg8_WNX%>SAS{U0~~Pd5Kgh5qb#{LyRt|7eg@d1Ti& q2!s2g7yef*k;cjG*xs(=PKIA7WsG1-&o}}8NIjB&nEl|{+y4hgp5Rvi literal 0 HcmV?d00001 diff --git a/docs/media/short-circuit-exception-catch.png b/docs/media/short-circuit-exception-catch.png new file mode 100644 index 0000000000000000000000000000000000000000..cc39a4124c934852f1905f294b9f52c7554f16b0 GIT binary patch literal 210844 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⪙B6GTjv#1%hr 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

vp_T8KH&f))jow4qRp&kZz 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

DvR&8??~udifg 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 CRLipf literal 0 HcmV?d00001 diff --git a/docs/media/unhandled-route-exception.png b/docs/media/unhandled-route-exception.png new file mode 100644 index 0000000000000000000000000000000000000000..ab3fc5a9c781d145815ca1a528288e8bfa6bcd80 GIT binary patch literal 186374 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 bqZv<)RXVv9TS9Fd;7d+MNxD!{-{-#oIN;pO literal 0 HcmV?d00001 diff --git a/examples/event_handler_rest/src/all_routes_middleware.py b/examples/event_handler_rest/src/all_routes_middleware.py new file mode 100644 index 00000000000..9e5d821dd1b --- /dev/null +++ b/examples/event_handler_rest/src/all_routes_middleware.py @@ -0,0 +1,32 @@ +import requests +from requests import Response + +from aws_lambda_powertools import Logger, Tracer +from aws_lambda_powertools.event_handler import APIGatewayRestResolver +from aws_lambda_powertools.logging import correlation_paths +from aws_lambda_powertools.utilities.typing import LambdaContext + +from .custom_middlewares import sanitise_exceptions, validate_correlation_id + +tracer = Tracer() +logger = Logger() +app = APIGatewayRestResolver() + +app.use(middlewares=[validate_correlation_id, sanitise_exceptions]) + + +@app.get("/todos") +@tracer.capture_method +def get_todos(): + todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos") + todos.raise_for_status() + + # for brevity, we'll limit to the first 10 only + return {"todos": todos.json()[:10]} + + +# You can continue to use other utilities just as before +@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST) +@tracer.capture_lambda_handler +def lambda_handler(event: dict, context: LambdaContext) -> dict: + return app.resolve(event, context) diff --git a/examples/event_handler_rest/src/custom_middlewares.py b/examples/event_handler_rest/src/custom_middlewares.py new file mode 100644 index 00000000000..ce260f08978 --- /dev/null +++ b/examples/event_handler_rest/src/custom_middlewares.py @@ -0,0 +1,30 @@ +from typing import Any, Callable + +from aws_lambda_powertools import Logger +from aws_lambda_powertools.event_handler import ApiGatewayResolver, Response +from aws_lambda_powertools.event_handler.exceptions import BadRequestError, InternalServerError, ServiceError + +logger = Logger() + + +def validate_correlation_id(app: ApiGatewayResolver, get_response: Callable[..., Any], **context_args) -> 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) + + +def sanitise_exceptions(app: ApiGatewayResolver, get_response: Callable[..., Any], **context_args) -> Response: + try: + # Get the Result from the next middleware + result: Response = get_response(app, **context_args) + except Exception as err: + logger.exception(err) + # Raise a clean error for ALL unexpected exceptions (ServiceError based Exceptions are okay) + if not isinstance(err, ServiceError): + raise InternalServerError("An error occurred during processing, please contact your administrator") + + # return the result when there are no exceptions + return result diff --git a/examples/event_handler_rest/src/middleware_func.py b/examples/event_handler_rest/src/middleware_func.py new file mode 100644 index 00000000000..66f74beb43d --- /dev/null +++ b/examples/event_handler_rest/src/middleware_func.py @@ -0,0 +1,16 @@ +from typing import Any, Callable + +from aws_lambda_powertools.event_handler import Response +from aws_lambda_powertools.event_handler.api_gateway import BaseRouter + + +def middleware_func(app: BaseRouter, get_response: Callable[..., Any], **context_args) -> Response: + # Do Before processing here + + # Get Next response + result = get_response(app, **context_args) + + # Do After processing here + + # return the response + return result diff --git a/examples/event_handler_rest/src/route_middleware.py b/examples/event_handler_rest/src/route_middleware.py new file mode 100644 index 00000000000..5156815e163 --- /dev/null +++ b/examples/event_handler_rest/src/route_middleware.py @@ -0,0 +1,30 @@ +import requests +from requests import Response + +from aws_lambda_powertools import Logger, Tracer +from aws_lambda_powertools.event_handler import APIGatewayRestResolver +from aws_lambda_powertools.logging import correlation_paths +from aws_lambda_powertools.utilities.typing import LambdaContext + +from .custom_middlewares import sanitise_exceptions, validate_correlation_id + +tracer = Tracer() +logger = Logger() +app = APIGatewayRestResolver() + + +@app.get("/todos", middlewares=[validate_correlation_id, sanitise_exceptions]) +@tracer.capture_method +def get_todos(): + todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos") + todos.raise_for_status() + + # for brevity, we'll limit to the first 10 only + return {"todos": todos.json()[:10]} + + +# You can continue to use other utilities just as before +@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST) +@tracer.capture_lambda_handler +def lambda_handler(event: dict, context: LambdaContext) -> dict: + return app.resolve(event, context) From fbb36abc6b0f8ddecc0b0cce15f7f3717657ea81 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Sun, 20 Aug 2023 17:57:37 +1000 Subject: [PATCH 36/85] feat(docs): Tidy up middleware docs and add to section to split routes --- docs/core/event_handler/api_gateway.md | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 228c9ee9c03..717a3b087f6 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -367,7 +367,7 @@ For convenience, these are the default values when using `CORSConfig` to enable Often there is a need to handle cross-cutting concerns or to add custom processing in a reusable way, middleware allows you to customize the request/response cycle for your API event handlers. Middleware enables you to add **before** and **after** processing for any API event, enabling you to pre-process the request and return early or to post-process the response to customize the API response. -???+ info "How Middleware Works" +??? info "How Middleware Works" Middleware functions are composed in a decorator style where each function controls the request/response flow and can make changes before or after the API handler is called. ![Image showing how the middleware flow works](/media/how-middleware-works-1.png) @@ -380,8 +380,9 @@ Often there is a need to handle cross-cutting concerns or to add custom processi 6. After the next middleware (or API handler) returns After processing may be run to post-process the response. 7. The response is returned by the Middleware function to the caller. -???+ tip "What Middleware is Responsible for" +??? tip "What Middleware is Responsible for" - They can be chained in a stack, so ensure it does only one thing to maximize re-usability and simplicity. + - Middleware must call the next middleware in the chain or your API handler will never be called. - Responsible for calling the next middleware function in the stack. - Can pre-process the Request data, change it or validate it before calling the next middleware function. - Returning early by throwing an exception or returning a valid response. @@ -406,7 +407,14 @@ Middleware can be represented by any valid Python Callable structure so long as The **app** parameter can also be a more specific type of Router such as ApiGatewayResolver, APIGatewayHttpResolver, ALBResolver, LambdaFunctionUrlResolver, or VPCLatticeResolver depending on your specific middleware requirements. +Middleware functions used in the Router instance will apply to all API routes and will always be processed first in the order they are added to the Router. Route specific middleware added to each route will then be processed in the order they were added in the route defintion. + ???+ tip + **Router Middleware processing Order** + + 1. Global middlewares defined on the parent Router + 2. Route specific Middlewares + To maximize the re-usability of your middleware functions we recommend using the **BaseRouter** or **Router** classes providing the **current_event** object contains the required fields for your middleware. ???+ warning "Ensure your middleware calls the Next one in the chain" @@ -427,6 +435,9 @@ The **app** parameter can also be a more specific type of Router such as ApiGate --8<-- "examples/event_handler_rest/src/custom_middlewares.py" ``` +???+ warning "Ensure your middleware returns the Next Response" + Your middleware functions must return the response from calling **get_response** or a modified version of the Response. If you do not return a value your API route will not work and return an API gateway error. + ### Fine grained responses You can use the `Response` class to have full control over the response. For example, you might want to add additional headers, cookies, or set a custom Content-type. @@ -564,6 +575,15 @@ Let's assume you have `split_route.py` as your Lambda function entrypoint and ro --8<-- "examples/event_handler_rest/src/split_route.py" ``` +#### Split Router Middleware + +The application of middleware functions for split routers is the same as using the main Resolver classes. When the split routes are combined in the API Rest resolver all Router based and route base middleware will be merged into the parent instance. + +???+ info "Split Router Middleware processing Order" + 1. Global Middleware defined on the parent Router + 2. Global Middleware for each split Router, in the order they are included + 3. Route specific Middlewares + #### Route prefix In the previous example, `split_route_module.py` routes had a `/todos` prefix. This might grow over time and become repetitive. From d4fc1ba051a41bd4530254c5b3b834912009207f Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Tue, 22 Aug 2023 12:01:18 +1000 Subject: [PATCH 37/85] feat(route): expose matched route instance to Resolver in additional context --- aws_lambda_powertools/event_handler/api_gateway.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 33ded346420..5afb85154ed 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -1062,7 +1062,12 @@ def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> Response try: # Reset Processed stack for Middleware (for debugging purposes) self._reset_processed_stack() - + + # Add matched Route reference into the Resolver context + self.append_context({ + route: route, + }) + return ResponseBuilder( self._to_response( route(router_middlewares=self._router_middlewares, app=self, route_arguments=route_arguments), From 837613b0fe0aa54bf26aa7e242cdd81a4c7c0421 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Tue, 22 Aug 2023 14:52:17 +1000 Subject: [PATCH 38/85] fix(resolver): Add 'powertols_route' to additional context --- aws_lambda_powertools/event_handler/api_gateway.py | 8 +++----- examples/event_handler_rest/src/all_routes_middleware.py | 3 +-- examples/event_handler_rest/src/route_middleware.py | 3 +-- 3 files changed, 5 insertions(+), 9 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 5afb85154ed..a3e5735bf20 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -1062,12 +1062,10 @@ def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> Response try: # Reset Processed stack for Middleware (for debugging purposes) self._reset_processed_stack() - + # Add matched Route reference into the Resolver context - self.append_context({ - route: route, - }) - + self.append_context(powertools_route=route) + return ResponseBuilder( self._to_response( route(router_middlewares=self._router_middlewares, app=self, route_arguments=route_arguments), diff --git a/examples/event_handler_rest/src/all_routes_middleware.py b/examples/event_handler_rest/src/all_routes_middleware.py index 9e5d821dd1b..b1e3a6a7e5a 100644 --- a/examples/event_handler_rest/src/all_routes_middleware.py +++ b/examples/event_handler_rest/src/all_routes_middleware.py @@ -1,4 +1,5 @@ import requests +from custom_middlewares import sanitise_exceptions, validate_correlation_id from requests import Response from aws_lambda_powertools import Logger, Tracer @@ -6,8 +7,6 @@ from aws_lambda_powertools.logging import correlation_paths from aws_lambda_powertools.utilities.typing import LambdaContext -from .custom_middlewares import sanitise_exceptions, validate_correlation_id - tracer = Tracer() logger = Logger() app = APIGatewayRestResolver() diff --git a/examples/event_handler_rest/src/route_middleware.py b/examples/event_handler_rest/src/route_middleware.py index 5156815e163..a135971c164 100644 --- a/examples/event_handler_rest/src/route_middleware.py +++ b/examples/event_handler_rest/src/route_middleware.py @@ -1,4 +1,5 @@ import requests +from custom_middlewares import sanitise_exceptions, validate_correlation_id from requests import Response from aws_lambda_powertools import Logger, Tracer @@ -6,8 +7,6 @@ from aws_lambda_powertools.logging import correlation_paths from aws_lambda_powertools.utilities.typing import LambdaContext -from .custom_middlewares import sanitise_exceptions, validate_correlation_id - tracer = Tracer() logger = Logger() app = APIGatewayRestResolver() From 49537a9a26d1a7049117e08642503ddae780f205 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 28 Aug 2023 12:06:54 +0200 Subject: [PATCH 39/85] docs: make intro punchy plus intro diagram Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 67 +++++++++++++------ .../event_handler_rest/src/middleware_func.py | 16 ----- .../src/middleware_getting_started.py | 32 +++++++++ 3 files changed, 77 insertions(+), 38 deletions(-) delete mode 100644 examples/event_handler_rest/src/middleware_func.py create mode 100644 examples/event_handler_rest/src/middleware_getting_started.py diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 717a3b087f6..f33b9c766c4 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -353,19 +353,43 @@ For convenience, these are the default values when using `CORSConfig` to enable ???+ tip "Multiple origins?" If you need to allow multiple origins, pass the additional origins using the `extra_origins` key. -| Key | Value | Note | -| -------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **[allow_origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin){target="_blank" rel="nofollow"}**: `str` | `*` | Only use the default value for development. **Never use `*` for production** unless your use case requires it | -| **[extra_origins](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin){target="_blank" rel="nofollow"}**: `List[str]` | `[]` | Additional origins to be allowed, in addition to the one specified in `allow_origin` | -| **[allow_headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers){target="_blank" rel="nofollow"}**: `List[str]` | `[Authorization, Content-Type, X-Amz-Date, X-Api-Key, X-Amz-Security-Token]` | Additional headers will be appended to the default list for your convenience | +| Key | Value | Note | +| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **[allow_origin](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin){target="_blank" rel="nofollow"}**: `str` | `*` | Only use the default value for development. **Never use `*` for production** unless your use case requires it | +| **[extra_origins](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin){target="_blank" rel="nofollow"}**: `List[str]` | `[]` | Additional origins to be allowed, in addition to the one specified in `allow_origin` | +| **[allow_headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Headers){target="_blank" rel="nofollow"}**: `List[str]` | `[Authorization, Content-Type, X-Amz-Date, X-Api-Key, X-Amz-Security-Token]` | Additional headers will be appended to the default list for your convenience | | **[expose_headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers){target="_blank" rel="nofollow"}**: `List[str]` | `[]` | Any additional header beyond the [safe listed by CORS specification](https://developer.mozilla.org/en-US/docs/Glossary/CORS-safelisted_response_header){target="_blank" rel="nofollow"}. | -| **[max_age](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age){target="_blank" rel="nofollow"}**: `int` | `` | Only for pre-flight requests if you choose to have your function to handle it instead of API Gateway | -| **[allow_credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials){target="_blank" rel="nofollow"}**: `bool` | `False` | Only necessary when you need to expose cookies, authorization headers or TLS client certificates. | +| **[max_age](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Max-Age){target="_blank" rel="nofollow"}**: `int` | `` | Only for pre-flight requests if you choose to have your function to handle it instead of API Gateway | +| **[allow_credentials](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Credentials){target="_blank" rel="nofollow"}**: `bool` | `False` | Only necessary when you need to expose cookies, authorization headers or TLS client certificates. | ### Middleware - -Often there is a need to handle cross-cutting concerns or to add custom processing in a reusable way, middleware allows you to customize the request/response cycle for your API event handlers. Middleware enables you to add **before** and **after** processing for any API event, enabling you to pre-process the request and return early or to post-process the response to customize the API response. +```mermaid +stateDiagram + direction LR + + EventHandler: GET /todo + Before: Before response + Next: get_response() + MiddlewareLoop: Middleware loop + AfterResponse: After response + MiddlewareFinished: Aggregated response + Response: Final response + + EventHandler --> Middleware: Has middleware? + state MiddlewareLoop { + direction LR + Middleware --> Before + Before --> Next + Next --> Middleware: More middlewares? + Next --> AfterResponse + } + AfterResponse --> MiddlewareFinished + MiddlewareFinished --> Response + EventHandler --> Response: No middleware +``` + +A middleware is a function you register per route to **intercept** or **enrich** a **request before** or **after** any response. ??? info "How Middleware Works" Middleware functions are composed in a decorator style where each function controls the request/response flow and can make changes before or after the API handler is called. @@ -390,20 +414,13 @@ Often there is a need to handle cross-cutting concerns or to add custom processi Middleware can be represented by any valid Python Callable structure so long as the call signature aligns with the following example and the function follows the processing cycle of **before**, **next (get_response)** and **after**. -=== "middleware_func.py" - ```python hl_lines="2 5 7 11" - def middleware_func(app: BaseRouter, get_response: Callable[..., Any], **context_args) -> Response: - # Do Before processing here - - # Get Next response - result = get_response(app, **context_args) - - # Do After processing here - +```python hl_lines="13 26" title="Your first middleware to log incoming events" +--8<-- "examples/event_handler_rest/src/middleware_getting_started.py" +``` - # return the response - return result - ``` +1. Testing test +2. Testing 2 +3. Testing 3 The **app** parameter can also be a more specific type of Router such as ApiGatewayResolver, APIGatewayHttpResolver, ALBResolver, LambdaFunctionUrlResolver, or VPCLatticeResolver depending on your specific middleware requirements. @@ -438,6 +455,12 @@ Middleware functions used in the Router instance will apply to all API routes an ???+ warning "Ensure your middleware returns the Next Response" Your middleware functions must return the response from calling **get_response** or a modified version of the Response. If you do not return a value your API route will not work and return an API gateway error. +#### Combining middlewares + +#### Returning early + +#### Common practices + ### Fine grained responses You can use the `Response` class to have full control over the response. For example, you might want to add additional headers, cookies, or set a custom Content-type. diff --git a/examples/event_handler_rest/src/middleware_func.py b/examples/event_handler_rest/src/middleware_func.py deleted file mode 100644 index 66f74beb43d..00000000000 --- a/examples/event_handler_rest/src/middleware_func.py +++ /dev/null @@ -1,16 +0,0 @@ -from typing import Any, Callable - -from aws_lambda_powertools.event_handler import Response -from aws_lambda_powertools.event_handler.api_gateway import BaseRouter - - -def middleware_func(app: BaseRouter, get_response: Callable[..., Any], **context_args) -> Response: - # Do Before processing here - - # Get Next response - result = get_response(app, **context_args) - - # Do After processing here - - # return the response - return result diff --git a/examples/event_handler_rest/src/middleware_getting_started.py b/examples/event_handler_rest/src/middleware_getting_started.py new file mode 100644 index 00000000000..6cf377e90d3 --- /dev/null +++ b/examples/event_handler_rest/src/middleware_getting_started.py @@ -0,0 +1,32 @@ +from typing import Any, Callable + +import requests + +from aws_lambda_powertools import Logger +from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response +from aws_lambda_powertools.event_handler.api_gateway import BaseRouter + +app = APIGatewayRestResolver() +logger = Logger() + + +def log_incoming_request(app: BaseRouter, get_response: Callable[..., Any], **context_args) -> Response: + # Do Before processing here + logger.info("Received request...", path=app.current_event.path) # (1)! + + # Get Next response + result = get_response(app, **context_args) # (2) + + # Do After processing here + + # return the response + return result # (3) + + +@app.get("/todos", middlewares=[log_incoming_request]) +def get_todos(): + todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos") + todos.raise_for_status() + + # for brevity, we'll limit to the first 10 only + return {"todos": todos.json()[:10]} From d0be0e41762796659b452284a7ce89ca26296ca9 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 28 Aug 2023 14:31:52 +0200 Subject: [PATCH 40/85] docs: use correlation id as first middleware Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 60 +++++++++++-------- .../src/middleware_getting_started.py | 31 ++++++---- 2 files changed, 54 insertions(+), 37 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index f33b9c766c4..feaf891d83f 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -373,7 +373,7 @@ stateDiagram Next: get_response() MiddlewareLoop: Middleware loop AfterResponse: After response - MiddlewareFinished: Aggregated response + MiddlewareFinished: Modified response Response: Final response EventHandler --> Middleware: Has middleware? @@ -391,36 +391,21 @@ stateDiagram A middleware is a function you register per route to **intercept** or **enrich** a **request before** or **after** any response. -??? info "How Middleware Works" - Middleware functions are composed in a decorator style where each function controls the request/response flow and can make changes before or after the API handler is called. - - ![Image showing how the middleware flow works](/media/how-middleware-works-1.png) +Each middleware function receives the following arguments: - 1. Powertools API Route handler executes API Route Handler (wrapped in composed middleware). - 2. Middleware function is called - 3. Before processing code - 4. Calls Next Middleware function (or registered API route handler) - 5. If the next function is middleware, it repeats these steps. The API route code runs and returns if it is the route handler. - 6. After the next middleware (or API handler) returns After processing may be run to post-process the response. - 7. The response is returned by the Middleware function to the caller. +1. **app**. An Event Handler instance so you can access incoming request information, Lambda context, etc. +2. **get_response**. A function to get the next middleware or route's response. +3. **`**context`**. A Middleware context that is propagated with dynamic route arguments and any previously injected metadata. -??? tip "What Middleware is Responsible for" - - They can be chained in a stack, so ensure it does only one thing to maximize re-usability and simplicity. - - Middleware must call the next middleware in the chain or your API handler will never be called. - - Responsible for calling the next middleware function in the stack. - - Can pre-process the Request data, change it or validate it before calling the next middleware function. - - Returning early by throwing an exception or returning a valid response. - - Can process the Response and alter its content depending on the middleware's purpose. - -Middleware can be represented by any valid Python Callable structure so long as the call signature aligns with the following example and the function follows the processing cycle of **before**, **next (get_response)** and **after**. - -```python hl_lines="13 26" title="Your first middleware to log incoming events" +```python hl_lines="12 23 30" title="Your first middleware to extract and inject correlation ID" --8<-- "examples/event_handler_rest/src/middleware_getting_started.py" ``` -1. Testing test -2. Testing 2 -3. Testing 3 +1. You can access current request like you normally would. +2. [Shared context is available](#sharing-contextual-data) to any middleware, Router and App instances.

Alternatively, you can use `**context` kwargs which will only be available for middlewares. +3. Get response from the next middleware (if any) or from `/todos` route. +4. You can manipulate headers, body, or status code before returning it +5. Register one or more middlewares in order of execution The **app** parameter can also be a more specific type of Router such as ApiGatewayResolver, APIGatewayHttpResolver, ALBResolver, LambdaFunctionUrlResolver, or VPCLatticeResolver depending on your specific middleware requirements. @@ -461,6 +446,29 @@ Middleware functions used in the Router instance will apply to all API routes an #### Common practices +#### Staging area + +??? info "How Middleware Works" + Middleware functions are composed in a decorator style where each function controls the request/response flow and can make changes before or after the API handler is called. + + ![Image showing how the middleware flow works](/media/how-middleware-works-1.png) + + 1. Powertools API Route handler executes API Route Handler (wrapped in composed middleware). + 2. Middleware function is called + 3. Before processing code + 4. Calls Next Middleware function (or registered API route handler) + 5. If the next function is middleware, it repeats these steps. The API route code runs and returns if it is the route handler. + 6. After the next middleware (or API handler) returns After processing may be run to post-process the response. + 7. The response is returned by the Middleware function to the caller. + +??? tip "What Middleware is Responsible for" + - They can be chained in a stack, so ensure it does only one thing to maximize re-usability and simplicity. + - Middleware must call the next middleware in the chain or your API handler will never be called. + - Responsible for calling the next middleware function in the stack. + - Can pre-process the Request data, change it or validate it before calling the next middleware function. + - Returning early by throwing an exception or returning a valid response. + - Can process the Response and alter its content depending on the middleware's purpose. + ### Fine grained responses You can use the `Response` class to have full control over the response. For example, you might want to add additional headers, cookies, or set a custom Content-type. diff --git a/examples/event_handler_rest/src/middleware_getting_started.py b/examples/event_handler_rest/src/middleware_getting_started.py index 6cf377e90d3..d5d06090201 100644 --- a/examples/event_handler_rest/src/middleware_getting_started.py +++ b/examples/event_handler_rest/src/middleware_getting_started.py @@ -1,32 +1,41 @@ -from typing import Any, Callable +from typing import Callable import requests from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response -from aws_lambda_powertools.event_handler.api_gateway import BaseRouter app = APIGatewayRestResolver() logger = Logger() -def log_incoming_request(app: BaseRouter, get_response: Callable[..., Any], **context_args) -> Response: - # Do Before processing here - logger.info("Received request...", path=app.current_event.path) # (1)! +def inject_correlation_id(app: APIGatewayRestResolver, get_response: Callable[..., Response], **context) -> Response: + request_id = app.current_event.request_context.request_id # (1)! - # Get Next response - result = get_response(app, **context_args) # (2) + # Use API Gateway REST API request ID if caller didn't include a correlation ID + correlation_id = app.current_event.headers.get("x-correlation-id", request_id) - # Do After processing here + # Inject correlation ID in shared context and Logger + app.append_context(correlation_id=correlation_id) # (2)! + logger.set_correlation_id(request_id) - # return the response - return result # (3) + # Get response from next middleware OR /todos route + result = get_response(app, **context) # (3)! + # Include Correlation ID in the response back to caller + result.headers["x-correlation-id"] = correlation_id # (4)! + return result -@app.get("/todos", middlewares=[log_incoming_request]) + +@app.get("/todos", middlewares=[inject_correlation_id]) # (5)! def get_todos(): todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos") todos.raise_for_status() # for brevity, we'll limit to the first 10 only return {"todos": todos.json()[:10]} + + +@logger.inject_lambda_context +def lambda_handler(event, context): + return app.resolve(event, context) From 2b6ee0b49109c8286a572a2f93ce0823902ec249 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 28 Aug 2023 14:52:01 +0200 Subject: [PATCH 41/85] docs: add output for completeness Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 26 +++++++++++++------ .../middleware_getting_started_output.json | 13 ++++++++++ 2 files changed, 31 insertions(+), 8 deletions(-) create mode 100644 examples/event_handler_rest/src/middleware_getting_started_output.json diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index feaf891d83f..e58bbcc2d0a 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -397,15 +397,25 @@ Each middleware function receives the following arguments: 2. **get_response**. A function to get the next middleware or route's response. 3. **`**context`**. A Middleware context that is propagated with dynamic route arguments and any previously injected metadata. -```python hl_lines="12 23 30" title="Your first middleware to extract and inject correlation ID" ---8<-- "examples/event_handler_rest/src/middleware_getting_started.py" -``` +Here's a sample middleware that extract and inject correlation ID, using `APIGatewayRestResolver`: + +=== "middleware_getting_started.py" + + ```python hl_lines="12 23 30" title="Your first middleware to extract and inject correlation ID" + --8<-- "examples/event_handler_rest/src/middleware_getting_started.py" + ``` -1. You can access current request like you normally would. -2. [Shared context is available](#sharing-contextual-data) to any middleware, Router and App instances.

Alternatively, you can use `**context` kwargs which will only be available for middlewares. -3. Get response from the next middleware (if any) or from `/todos` route. -4. You can manipulate headers, body, or status code before returning it -5. Register one or more middlewares in order of execution + 1. You can access current request like you normally would. + 2. [Shared context is available](#sharing-contextual-data) to any middleware, Router and App instances.

Alternatively, you can use `**context` kwargs which will only be available for middlewares. + 3. Get response from the next middleware (if any) or from `/todos` route. + 4. You can manipulate headers, body, or status code before returning it + 5. Register one or more middlewares in order of execution + +=== "middleware_getting_started_output.json" + + ```json hl_lines="9-10" + --8<-- "examples/event_handler_rest/src/middleware_getting_started_output.json" + ``` The **app** parameter can also be a more specific type of Router such as ApiGatewayResolver, APIGatewayHttpResolver, ALBResolver, LambdaFunctionUrlResolver, or VPCLatticeResolver depending on your specific middleware requirements. diff --git a/examples/event_handler_rest/src/middleware_getting_started_output.json b/examples/event_handler_rest/src/middleware_getting_started_output.json new file mode 100644 index 00000000000..aa669c57677 --- /dev/null +++ b/examples/event_handler_rest/src/middleware_getting_started_output.json @@ -0,0 +1,13 @@ +{ + "statusCode": 200, + "body": "{\"todos\":[{\"userId\":1,\"id\":1,\"title\":\"delectus aut autem\",\"completed\":false}]}", + "isBase64Encoded": false, + "multiValueHeaders": { + "Content-Type": [ + "application/json" + ], + "x-correlation-id": [ + "ccd87d70-7a3f-4aec-b1a8-a5a558c239b2" + ] + } +} \ No newline at end of file From 33cf3ad8ec7d5a6f50899a70d00e2d60b6a5e50e Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 28 Aug 2023 15:19:25 +0200 Subject: [PATCH 42/85] docs: grammar Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index e58bbcc2d0a..b3dbe4c155c 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -397,7 +397,7 @@ Each middleware function receives the following arguments: 2. **get_response**. A function to get the next middleware or route's response. 3. **`**context`**. A Middleware context that is propagated with dynamic route arguments and any previously injected metadata. -Here's a sample middleware that extract and inject correlation ID, using `APIGatewayRestResolver`: +Here's a sample middleware that extracts and injects correlation ID, using `APIGatewayRestResolver`: === "middleware_getting_started.py" @@ -408,8 +408,8 @@ Here's a sample middleware that extract and inject correlation ID, using `APIGat 1. You can access current request like you normally would. 2. [Shared context is available](#sharing-contextual-data) to any middleware, Router and App instances.

Alternatively, you can use `**context` kwargs which will only be available for middlewares. 3. Get response from the next middleware (if any) or from `/todos` route. - 4. You can manipulate headers, body, or status code before returning it - 5. Register one or more middlewares in order of execution + 4. You can manipulate headers, body, or status code before returning it. + 5. Register one or more middlewares in order of execution. === "middleware_getting_started_output.json" From 40b68a0afe24ce541e97e49b6bd939710c51145d Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 28 Aug 2023 15:35:08 +0200 Subject: [PATCH 43/85] docs: note that middleware works for any resolver Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index b3dbe4c155c..af1a930b09f 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -397,7 +397,7 @@ Each middleware function receives the following arguments: 2. **get_response**. A function to get the next middleware or route's response. 3. **`**context`**. A Middleware context that is propagated with dynamic route arguments and any previously injected metadata. -Here's a sample middleware that extracts and injects correlation ID, using `APIGatewayRestResolver`: +Here's a sample middleware that extracts and injects correlation ID, using `APIGatewayRestResolver` (works for any [Resolver](#event-resolvers)): === "middleware_getting_started.py" @@ -417,8 +417,6 @@ Here's a sample middleware that extracts and injects correlation ID, using `APIG --8<-- "examples/event_handler_rest/src/middleware_getting_started_output.json" ``` -The **app** parameter can also be a more specific type of Router such as ApiGatewayResolver, APIGatewayHttpResolver, ALBResolver, LambdaFunctionUrlResolver, or VPCLatticeResolver depending on your specific middleware requirements. - Middleware functions used in the Router instance will apply to all API routes and will always be processed first in the order they are added to the Router. Route specific middleware added to each route will then be processed in the order they were added in the route defintion. ???+ tip From 7bd0dbaaf89471c8514788c2179cdf3a986e2ee7 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 28 Aug 2023 17:04:55 +0200 Subject: [PATCH 44/85] docs: add global middlewares section Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 71 +- docs/diagram_src/api-middlewares.drawio | 1870 ++++++++--------- docs/media/how-middleware-works-1.png | Bin 179608 -> 0 bytes docs/media/how-middleware-works-2.png | Bin 188403 -> 0 bytes docs/media/middlewares_normal_processing.svg | 3 + docs/media/normal-processing.png | Bin 173988 -> 0 bytes docs/media/short-circuit-exception-catch.png | Bin 210844 -> 0 bytes docs/media/short-circuit-exception.png | Bin 204383 -> 0 bytes docs/media/short-circuit-response.png | Bin 204443 -> 0 bytes .../media/unhandled-route-exception-catch.png | Bin 202333 -> 0 bytes docs/media/unhandled-route-exception.png | Bin 186374 -> 0 bytes .../src/middleware_global_middlewares.py | 24 + .../middleware_global_middlewares_module.py | 33 + 13 files changed, 1044 insertions(+), 957 deletions(-) delete mode 100644 docs/media/how-middleware-works-1.png delete mode 100644 docs/media/how-middleware-works-2.png create mode 100644 docs/media/middlewares_normal_processing.svg delete mode 100644 docs/media/normal-processing.png delete mode 100644 docs/media/short-circuit-exception-catch.png delete mode 100644 docs/media/short-circuit-exception.png delete mode 100644 docs/media/short-circuit-response.png delete mode 100644 docs/media/unhandled-route-exception-catch.png delete mode 100644 docs/media/unhandled-route-exception.png create mode 100644 examples/event_handler_rest/src/middleware_global_middlewares.py create mode 100644 examples/event_handler_rest/src/middleware_global_middlewares_module.py diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index af1a930b09f..3fdc84f64be 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -417,38 +417,32 @@ Here's a sample middleware that extracts and injects correlation ID, using `APIG --8<-- "examples/event_handler_rest/src/middleware_getting_started_output.json" ``` -Middleware functions used in the Router instance will apply to all API routes and will always be processed first in the order they are added to the Router. Route specific middleware added to each route will then be processed in the order they were added in the route defintion. +#### Global middlewares -???+ tip - **Router Middleware processing Order** +

+![Combining middlewares](../../media/middlewares_normal_processing.svg) +_Request flowing through multiple registered middlewares_ +
- 1. Global middlewares defined on the parent Router - 2. Route specific Middlewares +You can use `app.use` to register middlewares that should run for all routes. These so called **global middlewares are called before those defined at the route level.** - To maximize the re-usability of your middleware functions we recommend using the **BaseRouter** or **Router** classes providing the **current_event** object contains the required fields for your middleware. +Here's an example where we want to log request and response for debugging purposes. -???+ warning "Ensure your middleware calls the Next one in the chain" - The middleware stack processing relies on each middleware function calling the next and also returning the reponse or raising an exception. If you do not pass control to the next middleware function in the chain, your API route handler will never be called. +!!! note "Use [debug mode](#debug-mode) if you have this exact need instead." -=== "route_middleware.py" - ```python hl_lines="9 16" - --8<-- "examples/event_handler_rest/src/route_middleware.py" - ``` +=== "middleware_global_middlewares.py" -=== "all_routes_middleware.py" - ```python hl_lines="9 15" - --8<-- "examples/event_handler_rest/src/all_routes_middleware.py" + ```python hl_lines="10" title="Registering global and route middlewares" + --8<-- "examples/event_handler_rest/src/middleware_global_middlewares.py" ``` -=== "custom_middlewares.py" - ```python hl_lines="12 14 18 21 23" - --8<-- "examples/event_handler_rest/src/custom_middlewares.py" - ``` + 1. A separate file where our middlewares are to keep this example focused. -???+ warning "Ensure your middleware returns the Next Response" - Your middleware functions must return the response from calling **get_response** or a modified version of the Response. If you do not return a value your API route will not work and return an API gateway error. +=== "middleware_global_middlewares_module.py" -#### Combining middlewares + ```python hl_lines="9" + --8<-- "examples/event_handler_rest/src/middleware_global_middlewares_module.py" + ``` #### Returning early @@ -477,6 +471,39 @@ Middleware functions used in the Router instance will apply to all API routes an - Returning early by throwing an exception or returning a valid response. - Can process the Response and alter its content depending on the middleware's purpose. +???+ warning "Ensure your middleware returns the Next Response" + Your middleware functions must return the response from calling **get_response** or a modified version of the Response. If you do not return a value your API route will not work and return an API gateway error. + +**This should go under the Router area since we haven't introduced it yet** + +Middleware functions used in the Router instance will apply to all API routes and will always be processed first in the order they are added to the Router. Route specific middleware added to each route will then be processed in the order they were added in the route defintion. + +???+ tip + **Router Middleware processing Order** + + 1. Global middlewares defined on the parent Router + 2. Route specific Middlewares + + To maximize the re-usability of your middleware functions we recommend using the **BaseRouter** or **Router** classes providing the **current_event** object contains the required fields for your middleware. + +???+ warning "Ensure your middleware calls the Next one in the chain" + The middleware stack processing relies on each middleware function calling the next and also returning the reponse or raising an exception. If you do not pass control to the next middleware function in the chain, your API route handler will never be called. + +=== "route_middleware.py" + ```python hl_lines="9 16" + --8<-- "examples/event_handler_rest/src/route_middleware.py" + ``` + +=== "all_routes_middleware.py" + ```python hl_lines="9 15" + --8<-- "examples/event_handler_rest/src/all_routes_middleware.py" + ``` + +=== "custom_middlewares.py" + ```python hl_lines="12 14 18 21 23" + --8<-- "examples/event_handler_rest/src/custom_middlewares.py" + ``` + ### Fine grained responses You can use the `Response` class to have full control over the response. For example, you might want to add additional headers, cookies, or set a custom Content-type. diff --git a/docs/diagram_src/api-middlewares.drawio b/docs/diagram_src/api-middlewares.drawio index 69be87f4ed1..e76cb313714 100644 --- a/docs/diagram_src/api-middlewares.drawio +++ b/docs/diagram_src/api-middlewares.drawio @@ -1,935 +1,935 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/media/how-middleware-works-1.png b/docs/media/how-middleware-works-1.png deleted file mode 100644 index e858d471b1e78ce37eca5002e4a05877633325de..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 179608 zcmeEP1wd0>8&>R=Pz)>t#XuL7iNGiY32B3Wz+i*1!8S@1YynZkZWQwq8ygV=vAYWc z1v?Q@Q2%qcd$!AVVN=G~(C_C*c6WDo?|JJv?|I+nBs!0_ZPmO}^Lq8_wX(OPxYnzu zmRPS|{ZUODgCmE#wQm6asn2z_wXC<}lFrL|YU4Nati5=l(SZymt)4#FO7NFHi9ly_ zdHQ6EK8a+_r1|qWY!>(v91mp&FajC00Kt1C0*P!$Ff$|$awC!T$ri?@$S?8$V-tdp z;CyNjjfGywkv);YWK#7>HpT-8;8F&TRDTAG$L7-Y$(G=?J&Q+Uf`7qb@Y`t&_~ixu zPbByfjeSk~fIlt5!k9Eqn%^h}54j52bO6}|95xtb=jQ03PqG4kGZ`T?@Q*FcKZK2Z zB!EMW8o*$K(@DeuCIigCAuBqE9STmeArg%S5C#~Vl8pzD%m#sXM2~7iG9Dnf%Q4hI zDu;pjI%E_gX&f#C3<-aL;DwPlXgq3=;Al8ECYlf)YUX6Z4tMc(VhwWl;RuF=7ZXMk zoD)EcWcY(SK|UDBnz&@qJpR6-x-}9Wf;l`2w>8ps2rMM6q^&mH6)5(9ezh>v@M4kMt5Wf z@Wl`iEw~8L)QtZTFqScbBPOOsf^Q1qz`H@uKn{#yOhmt)2yPyEw4ew^0DLy|L>`;X z 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 UM^nHLJ76$d^hxU~OOLp}05VVd2><{9 diff --git a/docs/media/middlewares_normal_processing.svg b/docs/media/middlewares_normal_processing.svg new file mode 100644 index 00000000000..52b1f4cca83 --- /dev/null +++ b/docs/media/middlewares_normal_processing.svg @@ -0,0 +1,3 @@ + + +
Event
Handler
Event<br>Handler
API Route
Handler
API Route<br>Handler
Before
Before
After
After
Next
Next
Middleware-1
Middleware-1
Before
Before
After
After
Next
Next
Middleware-2
Middleware-2
Before
Before
After
After
Next
Next
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
@app.get("/todos")
@app.get("/todos")
\ No newline at end of file diff --git a/docs/media/normal-processing.png b/docs/media/normal-processing.png deleted file mode 100644 index 5d1c3cfb9c531ad05c55624c50a06759c5f735e9..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 173988 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

vp_T8KH&f))jow4qRp&kZz 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

DvR&8??~udifg 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 CRLipf diff --git a/docs/media/unhandled-route-exception.png b/docs/media/unhandled-route-exception.png deleted file mode 100644 index ab3fc5a9c781d145815ca1a528288e8bfa6bcd80..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 186374 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 bqZv<)RXVv9TS9Fd;7d+MNxD!{-{-#oIN;pO diff --git a/examples/event_handler_rest/src/middleware_global_middlewares.py b/examples/event_handler_rest/src/middleware_global_middlewares.py new file mode 100644 index 00000000000..c8f3945a005 --- /dev/null +++ b/examples/event_handler_rest/src/middleware_global_middlewares.py @@ -0,0 +1,24 @@ +import middleware_global_middlewares_module # (1)! +import requests + +from aws_lambda_powertools import Logger +from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response + +app = APIGatewayRestResolver() +logger = Logger() + +app.use(middlewares=[middleware_global_middlewares_module.log_request_response]) + + +@app.get("/todos", middlewares=[middleware_global_middlewares_module.inject_correlation_id]) +def get_todos(): + todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos") + todos.raise_for_status() + + # for brevity, we'll limit to the first 10 only + return {"todos": todos.json()[:10]} + + +@logger.inject_lambda_context +def lambda_handler(event, context): + return app.resolve(event, context) diff --git a/examples/event_handler_rest/src/middleware_global_middlewares_module.py b/examples/event_handler_rest/src/middleware_global_middlewares_module.py new file mode 100644 index 00000000000..fb7f0123d67 --- /dev/null +++ b/examples/event_handler_rest/src/middleware_global_middlewares_module.py @@ -0,0 +1,33 @@ +from typing import Callable + +from aws_lambda_powertools import Logger +from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response + +logger = Logger() + + +def log_request_response(app: APIGatewayRestResolver, get_response: Callable[..., Response], **context) -> Response: + logger.info("Incoming request", path=app.current_event.path, request=app.current_event.raw_event) + + result = get_response(app, **context) + logger.info("Response received", response=result.__dict__) + + return result + + +def inject_correlation_id(app: APIGatewayRestResolver, get_response: Callable[..., Response], **context) -> 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 + correlation_id = app.current_event.headers.get("x-correlation-id", request_id) + + # Inject correlation ID in shared context and Logger + app.append_context(correlation_id=correlation_id) + logger.set_correlation_id(request_id) + + # Get response from next middleware OR /todos route + result = get_response(app, **context) + + # Include Correlation ID in the response back to caller + result.headers["x-correlation-id"] = correlation_id + return result From 947d0ce265d5f2d8c3815aaef733b1b1595a9b25 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 28 Aug 2023 18:23:12 +0200 Subject: [PATCH 45/85] docs: additional ctx for global middlewares order Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 22 ++++++++++++++----- .../src/middleware_global_middlewares.py | 2 +- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 3fdc84f64be..c6154fa7343 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -424,19 +424,31 @@ Here's a sample middleware that extracts and injects correlation ID, using `APIG _Request flowing through multiple registered middlewares_ -You can use `app.use` to register middlewares that should run for all routes. These so called **global middlewares are called before those defined at the route level.** +You can use `app.use` to register middlewares that should always run regardless of the route, also known as global middlewares. -Here's an example where we want to log request and response for debugging purposes. - -!!! note "Use [debug mode](#debug-mode) if you have this exact need instead." +Event Handler **calls global middlewares first**, then middlewares defined at the route level. Here's an example with both middlewares: === "middleware_global_middlewares.py" - ```python hl_lines="10" title="Registering global and route middlewares" + > Use [debug mode](#debug-mode) if you need to log request/response. + + ```python hl_lines="10" --8<-- "examples/event_handler_rest/src/middleware_global_middlewares.py" ``` 1. A separate file where our middlewares are to keep this example focused. + 2. We register `log_request_response` as a global middleware to run before middleware. + ```mermaid + stateDiagram + direction LR + + GlobalMiddleware: Log request response + RouteMiddleware: Inject correlation ID + EventHandler: Event Handler + + EventHandler --> GlobalMiddleware + GlobalMiddleware --> RouteMiddleware + ``` === "middleware_global_middlewares_module.py" diff --git a/examples/event_handler_rest/src/middleware_global_middlewares.py b/examples/event_handler_rest/src/middleware_global_middlewares.py index c8f3945a005..11da3e27973 100644 --- a/examples/event_handler_rest/src/middleware_global_middlewares.py +++ b/examples/event_handler_rest/src/middleware_global_middlewares.py @@ -7,7 +7,7 @@ app = APIGatewayRestResolver() logger = Logger() -app.use(middlewares=[middleware_global_middlewares_module.log_request_response]) +app.use(middlewares=[middleware_global_middlewares_module.log_request_response]) # (2)! @app.get("/todos", middlewares=[middleware_global_middlewares_module.inject_correlation_id]) From efee2ae85fa24d6671b9b50ecb38f88d22ae7aff Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 28 Aug 2023 19:25:42 +0200 Subject: [PATCH 46/85] docs: add early return section Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 36 ++++++++++++++++++- docs/media/middlewares_early_return.svg | 3 ++ .../src/middleware_early_return.py | 28 +++++++++++++++ .../src/middleware_early_return_output.json | 10 ++++++ .../middleware_global_middlewares_module.py | 10 ++++++ 5 files changed, 86 insertions(+), 1 deletion(-) create mode 100644 docs/media/middlewares_early_return.svg create mode 100644 examples/event_handler_rest/src/middleware_early_return.py create mode 100644 examples/event_handler_rest/src/middleware_early_return_output.json diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index c6154fa7343..5c8afd72423 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -452,12 +452,46 @@ Event Handler **calls global middlewares first**, then middlewares defined at th === "middleware_global_middlewares_module.py" - ```python hl_lines="9" + ```python hl_lines="10" --8<-- "examples/event_handler_rest/src/middleware_global_middlewares_module.py" ``` #### Returning early +

+![Short-circuiting middleware chain](../../media/middlewares_early_return.svg) +_Interrupting request flow by returning early_ +
+ +Imagine you want to stop processing a request if something is missing, or return immediately if you've seen this request before. + +In these scenarios, you short-circuit the middleware processing logic by raising a [HTTP Error](#raising-http-errors), or returning a [Response object](#fine-grained-responses). Event Handler will understand it now needs to run each “After” logic left in the chain. + +Here's an example where we now prevent any request that doesn't include a correlation ID header: + +=== "middleware_early_return.py" + + ```python hl_lines="12" + --8<-- "examples/event_handler_rest/src/middleware_early_return.py" + ``` + + 1. This middleware will raise an exception if correlation ID header is missing. + 2. This code section will not run if `enforce_correlation_id` returns early. + +=== "middleware_global_middlewares_module.py" + + ```python hl_lines="37 40" + --8<-- "examples/event_handler_rest/src/middleware_global_middlewares_module.py" + ``` + + 1. Raising an exception OR returning a Response object early will short-circuit the middleware chain. + +=== "middleware_early_return_output.json" + + ```python hl_lines="2-3" + --8<-- "examples/event_handler_rest/src/middleware_early_return_output.json" + ``` + #### Common practices #### Staging area diff --git a/docs/media/middlewares_early_return.svg b/docs/media/middlewares_early_return.svg new file mode 100644 index 00000000000..5de73b39418 --- /dev/null +++ b/docs/media/middlewares_early_return.svg @@ -0,0 +1,3 @@ + + +
Event
Handler
Event<br>Handler
API Route
Handler
API Route<br>Handler
Before
Before
After
After
Next
Next
Middleware-1
Middleware-1
Before
Before
After
After
Next
Next
Middleware-2
Middleware-2
Before
Before
After
After
Next
Next
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
Short-Circuited Response from Middleware-3
<font style="font-size: 14px"><b>Short-Circuited Response from Middleware-3</b></font>
Middleware and Route Handler beyond
Middleware-3 not processed
[Not supported by viewer]
Run "After" logic for Middleware-2 then Middleware-1
<span style="font-size: 14px"><b>Run "After" logic for Middleware-2 then Middleware-1<br></b></span>
Not called due to early return in previous step
<b>Not called due to early return in previous step<br></b>
@app.get("/todos")
@app.get("/todos")
\ No newline at end of file diff --git a/examples/event_handler_rest/src/middleware_early_return.py b/examples/event_handler_rest/src/middleware_early_return.py new file mode 100644 index 00000000000..1d8b3af1592 --- /dev/null +++ b/examples/event_handler_rest/src/middleware_early_return.py @@ -0,0 +1,28 @@ +import middleware_global_middlewares_module +import requests + +from aws_lambda_powertools import Logger +from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response + +app = APIGatewayRestResolver() +logger = Logger() +app.use( + middlewares=[ + middleware_global_middlewares_module.log_request_response, + middleware_global_middlewares_module.enforce_correlation_id, # (1)! + ], +) + + +@app.get("/todos") +def get_todos(): + todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos") # (2)! + todos.raise_for_status() + + # for brevity, we'll limit to the first 10 only + return {"todos": todos.json()[:10]} + + +@logger.inject_lambda_context +def lambda_handler(event, context): + return app.resolve(event, context) diff --git a/examples/event_handler_rest/src/middleware_early_return_output.json b/examples/event_handler_rest/src/middleware_early_return_output.json new file mode 100644 index 00000000000..16299f2cfd7 --- /dev/null +++ b/examples/event_handler_rest/src/middleware_early_return_output.json @@ -0,0 +1,10 @@ +{ + "statusCode": 400, + "body": "{'statusCode':400,'message':'Correlation ID header is now mandatory.'}", + "isBase64Encoded": false, + "multiValueHeaders": { + "Content-Type": [ + "application/json" + ] + } +} \ No newline at end of file diff --git a/examples/event_handler_rest/src/middleware_global_middlewares_module.py b/examples/event_handler_rest/src/middleware_global_middlewares_module.py index fb7f0123d67..a0fbad53be1 100644 --- a/examples/event_handler_rest/src/middleware_global_middlewares_module.py +++ b/examples/event_handler_rest/src/middleware_global_middlewares_module.py @@ -2,6 +2,7 @@ from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response +from aws_lambda_powertools.event_handler.exceptions import BadRequestError logger = Logger() @@ -31,3 +32,12 @@ def inject_correlation_id(app: APIGatewayRestResolver, get_response: Callable[.. # 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: Callable[..., Response], **context) -> Response: + # If missing mandatory header raise an error + if not app.current_event.get_header_value("x-correlation-id", case_sensitive=False): + raise BadRequestError("Correlation ID header is now mandatory.") # (1)! + + # Get the response from the next middleware and return it + return get_response(app, **context) From 741f2a5e4de675d355999727952bca9eaf84e4f1 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Wed, 30 Aug 2023 20:25:50 +1000 Subject: [PATCH 47/85] feat(route): expose route instance in ephemeral context dict --- aws_lambda_powertools/event_handler/api_gateway.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index a3e5735bf20..b385e32498b 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -1064,7 +1064,7 @@ def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> Response self._reset_processed_stack() # Add matched Route reference into the Resolver context - self.append_context(powertools_route=route) + self.append_context(_route=route) return ResponseBuilder( self._to_response( From 388592fb7b39f4bae31fa201ae51cd2c076b77fa Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Wed, 30 Aug 2023 21:44:31 +1000 Subject: [PATCH 48/85] feat(middlewwares): Expand tests to incdlue core gateway types --- tests/events/apiGatewayProxyV2Event_GET.json | 68 +++++++ ...wayProxyV2SchemaMiddlwareInvalidEvent.json | 69 +++++++ ...tewayProxyV2SchemaMiddlwareValidEvent.json | 69 +++++++ .../event_handler/test_api_middlewares.py | 181 ++++++++++++------ 4 files changed, 329 insertions(+), 58 deletions(-) create mode 100644 tests/events/apiGatewayProxyV2Event_GET.json create mode 100644 tests/events/apiGatewayProxyV2SchemaMiddlwareInvalidEvent.json create mode 100644 tests/events/apiGatewayProxyV2SchemaMiddlwareValidEvent.json diff --git a/tests/events/apiGatewayProxyV2Event_GET.json b/tests/events/apiGatewayProxyV2Event_GET.json new file mode 100644 index 00000000000..f411ea655d0 --- /dev/null +++ b/tests/events/apiGatewayProxyV2Event_GET.json @@ -0,0 +1,68 @@ +{ + "version": "2.0", + "routeKey": "$default", + "rawPath": "/my/path", + "rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value", + "cookies": [ + "cookie1", + "cookie2" + ], + "headers": { + "Header1": "value1", + "Header2": "value1,value2" + }, + "queryStringParameters": { + "parameter1": "value1,value2", + "parameter2": "value" + }, + "requestContext": { + "accountId": "123456789012", + "apiId": "api-id", + "authentication": { + "clientCert": { + "clientCertPem": "CERT_CONTENT", + "subjectDN": "www.example.com", + "issuerDN": "Example issuer", + "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", + "validity": { + "notBefore": "May 28 12:30:02 2019 GMT", + "notAfter": "Aug 5 09:36:04 2021 GMT" + } + } + }, + "authorizer": { + "jwt": { + "claims": { + "claim1": "value1", + "claim2": "value2" + }, + "scopes": [ + "scope1", + "scope2" + ] + } + }, + "domainName": "id.execute-api.us-east-1.amazonaws.com", + "domainPrefix": "id", + "http": { + "method": "GET", + "path": "/my/path", + "protocol": "HTTP/1.1", + "sourceIp": "192.168.0.1/32", + "userAgent": "agent" + }, + "requestId": "id", + "routeKey": "$default", + "stage": "$default", + "time": "12/Mar/2020:19:03:58 +0000", + "timeEpoch": 1583348638390 + }, + "pathParameters": { + "parameter1": "value1" + }, + "isBase64Encoded": false, + "stageVariables": { + "stageVariable1": "value1", + "stageVariable2": "value2" + } +} diff --git a/tests/events/apiGatewayProxyV2SchemaMiddlwareInvalidEvent.json b/tests/events/apiGatewayProxyV2SchemaMiddlwareInvalidEvent.json new file mode 100644 index 00000000000..d2f4c404c79 --- /dev/null +++ b/tests/events/apiGatewayProxyV2SchemaMiddlwareInvalidEvent.json @@ -0,0 +1,69 @@ +{ + "version": "2.0", + "routeKey": "$default", + "rawPath": "/my/path", + "rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value", + "cookies": [ + "cookie1", + "cookie2" + ], + "headers": { + "Header1": "value1", + "Header2": "value1,value2" + }, + "queryStringParameters": { + "parameter1": "value1,value2", + "parameter2": "value" + }, + "requestContext": { + "accountId": "123456789012", + "apiId": "api-id", + "authentication": { + "clientCert": { + "clientCertPem": "CERT_CONTENT", + "subjectDN": "www.example.com", + "issuerDN": "Example issuer", + "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", + "validity": { + "notBefore": "May 28 12:30:02 2019 GMT", + "notAfter": "Aug 5 09:36:04 2021 GMT" + } + } + }, + "authorizer": { + "jwt": { + "claims": { + "claim1": "value1", + "claim2": "value2" + }, + "scopes": [ + "scope1", + "scope2" + ] + } + }, + "domainName": "id.execute-api.us-east-1.amazonaws.com", + "domainPrefix": "id", + "http": { + "method": "POST", + "path": "/my/path", + "protocol": "HTTP/1.1", + "sourceIp": "192.168.0.1/32", + "userAgent": "agent" + }, + "requestId": "id", + "routeKey": "$default", + "stage": "$default", + "time": "12/Mar/2020:19:03:58 +0000", + "timeEpoch": 1583348638390 + }, + "body": "{\"username\": \"lessa\"}", + "pathParameters": { + "parameter1": "value1" + }, + "isBase64Encoded": false, + "stageVariables": { + "stageVariable1": "value1", + "stageVariable2": "value2" + } +} diff --git a/tests/events/apiGatewayProxyV2SchemaMiddlwareValidEvent.json b/tests/events/apiGatewayProxyV2SchemaMiddlwareValidEvent.json new file mode 100644 index 00000000000..7be3d1194d2 --- /dev/null +++ b/tests/events/apiGatewayProxyV2SchemaMiddlwareValidEvent.json @@ -0,0 +1,69 @@ +{ + "version": "2.0", + "routeKey": "$default", + "rawPath": "/my/path", + "rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value", + "cookies": [ + "cookie1", + "cookie2" + ], + "headers": { + "Header1": "value1", + "Header2": "value1,value2" + }, + "queryStringParameters": { + "parameter1": "value1,value2", + "parameter2": "value" + }, + "requestContext": { + "accountId": "123456789012", + "apiId": "api-id", + "authentication": { + "clientCert": { + "clientCertPem": "CERT_CONTENT", + "subjectDN": "www.example.com", + "issuerDN": "Example issuer", + "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", + "validity": { + "notBefore": "May 28 12:30:02 2019 GMT", + "notAfter": "Aug 5 09:36:04 2021 GMT" + } + } + }, + "authorizer": { + "jwt": { + "claims": { + "claim1": "value1", + "claim2": "value2" + }, + "scopes": [ + "scope1", + "scope2" + ] + } + }, + "domainName": "id.execute-api.us-east-1.amazonaws.com", + "domainPrefix": "id", + "http": { + "method": "POST", + "path": "/my/path", + "protocol": "HTTP/1.1", + "sourceIp": "192.168.0.1/32", + "userAgent": "agent" + }, + "requestId": "id", + "routeKey": "$default", + "stage": "$default", + "time": "12/Mar/2020:19:03:58 +0000", + "timeEpoch": 1583348638390 + }, + "body": "{\"message\": \"hello world\", \"username\": \"lessa\"}", + "pathParameters": { + "parameter1": "value1" + }, + "isBase64Encoded": false, + "stageVariables": { + "stageVariable1": "value1", + "stageVariable2": "value2" + } +} diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index 13336f61b68..70dc5f7192e 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -1,24 +1,31 @@ +import pytest + from aws_lambda_powertools.event_handler import content_types from aws_lambda_powertools.event_handler.api_gateway import ( + APIGatewayHttpResolver, ApiGatewayResolver, + APIGatewayRestResolver, ProxyEventType, Response, Router, ) from aws_lambda_powertools.event_handler.exceptions import BadRequestError from aws_lambda_powertools.event_handler.middlewares import SchemaValidationMiddleware -from aws_lambda_powertools.utilities.data_classes import ( - APIGatewayProxyEvent, -) from tests.functional.utils import load_event -LOAD_GW_EVENT = load_event("apiGatewayProxyEvent.json") - +API_REST_EVENT = load_event("apiGatewayProxyEvent.json") +API_RESTV2_EVENT = load_event("apiGatewayProxyV2Event_GET.json") -def test_route_with_middleware(): - # GIVEN a Rest API Gateway proxy type event - app = ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent) +@pytest.mark.parametrize( + "app, event", + [ + (ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), API_REST_EVENT), + (APIGatewayRestResolver(), API_REST_EVENT), + (APIGatewayHttpResolver(), API_RESTV2_EVENT), + ], +) +def test_route_with_middleware(app, event): # define custom middleware to inject new argument - "custom" def middleware_1(app, get_response, **kwargs): # inject a variable into the kwargs @@ -35,25 +42,28 @@ def middleware_2(app, get_response, **kwargs): @app.get("/my/path", middlewares=[middleware_1, middleware_2]) def get_lambda(another_one: int, custom: str) -> Response: - assert isinstance(app.current_event, APIGatewayProxyEvent) assert another_one == 6 assert custom == "custom" return Response(200, content_types.TEXT_HTML, "foo") # WHEN calling the event handler - result = app(LOAD_GW_EVENT, {}) + result = app(event, {}) # THEN process event correctly # AND set the current_event type as APIGatewayProxyEvent assert result["statusCode"] == 200 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] assert result["body"] == "foo" -def test_with_router_middleware(): - # GIVEN a Rest API Gateway proxy type event - app = ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent) - +@pytest.mark.parametrize( + "app, event", + [ + (ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), API_REST_EVENT), + (APIGatewayRestResolver(), API_REST_EVENT), + (APIGatewayHttpResolver(), API_RESTV2_EVENT), + ], +) +def test_with_router_middleware(app, event): # define custom middleware to inject new argument - "custom" def middleware_1(app, get_response, **kwargs): # inject a variable into the kwargs @@ -72,25 +82,28 @@ def middleware_2(app, get_response, **kwargs): @app.get("/my/path", middlewares=[middleware_2]) def get_lambda(another_one: int, custom: str) -> Response: - assert isinstance(app.current_event, APIGatewayProxyEvent) assert another_one == 6 assert custom == "custom" return Response(200, content_types.TEXT_HTML, "foo") # WHEN calling the event handler - result = app(LOAD_GW_EVENT, {}) + result = app(event, {}) # THEN process event correctly # AND set the current_event type as APIGatewayProxyEvent assert result["statusCode"] == 200 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] assert result["body"] == "foo" -def test_dynamic_route_with_middleware(): - # GIVEN - app = ApiGatewayResolver() - +@pytest.mark.parametrize( + "app, event", + [ + (ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), API_REST_EVENT), + (APIGatewayRestResolver(), API_REST_EVENT), + (APIGatewayHttpResolver(), API_RESTV2_EVENT), + ], +) +def test_dynamic_route_with_middleware(app, event): def middleware_one(app, get_response, **kwargs): # inject a variable into the kwargs response = get_response(app, injected="injected_value", **kwargs) @@ -105,18 +118,22 @@ def get_lambda(my_id: str, name: str, injected: str) -> Response: return Response(200, content_types.TEXT_HTML, my_id) # WHEN calling the event handler - result = app(LOAD_GW_EVENT, {}) + result = app(event, {}) # THEN assert result["statusCode"] == 200 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] assert result["body"] == "path" -def test_middleware_early_return(): - # GIVEN - app = ApiGatewayResolver() - +@pytest.mark.parametrize( + "app, event", + [ + (ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), API_REST_EVENT), + (APIGatewayRestResolver(), API_REST_EVENT), + (APIGatewayHttpResolver(), API_RESTV2_EVENT), + ], +) +def test_middleware_early_return(app, event): def middleware_one(app, get_response, **context): # inject a variable into the kwargs response = get_response(app, injected="injected_value", **context) @@ -140,74 +157,117 @@ def get_lambda(my_id: str, name: str, injected: str) -> Response: return Response(200, content_types.TEXT_HTML, my_id) # WHEN calling the event handler - result = app(LOAD_GW_EVENT, {}) + result = app(event, {}) # THEN assert result["statusCode"] == 400 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] assert result["body"] == "bad_response" -def test_pass_schema_validation(validation_schema): - # GIVEN - app = ApiGatewayResolver() - +@pytest.mark.parametrize( + "app, event", + [ + ( + ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), + load_event("apigatewayeSchemaMiddlwareValidEvent.json"), + ), + ( + APIGatewayRestResolver(), + load_event("apigatewayeSchemaMiddlwareValidEvent.json"), + ), + ( + APIGatewayHttpResolver(), + load_event("apiGatewayProxyV2SchemaMiddlwareValidEvent.json"), + ), + ], +) +def test_pass_schema_validation(app, event, validation_schema): @app.post("/my/path", middlewares=[SchemaValidationMiddleware(validation_schema)]) def post_lambda() -> Response: return Response(200, content_types.TEXT_HTML, "path") # WHEN calling the event handler - result = app(load_event("apigatewayeSchemaMiddlwareValidEvent.json"), {}) + result = app(event, {}) # THEN assert result["statusCode"] == 200 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] assert result["body"] == "path" -def test_fail_schema_validation(validation_schema): - # GIVEN - app = ApiGatewayResolver() - +@pytest.mark.parametrize( + "app, event", + [ + ( + ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), + load_event("apigatewayeSchemaMiddlwareInvalidEvent.json"), + ), + ( + APIGatewayRestResolver(), + load_event("apigatewayeSchemaMiddlwareInvalidEvent.json"), + ), + ( + APIGatewayHttpResolver(), + load_event("apiGatewayProxyV2SchemaMiddlwareInvalidEvent.json"), + ), + ], +) +def test_fail_schema_validation(app, event, validation_schema): @app.post("/my/path", middlewares=[SchemaValidationMiddleware(validation_schema)]) def post_lambda() -> Response: return Response(200, content_types.TEXT_HTML, "Should not be returned") # WHEN calling the event handler - result = app(load_event("apigatewayeSchemaMiddlwareInvalidEvent.json"), {}) + result = app(event, {}) print(f"\nRESULT:::{result}") # THEN assert result["statusCode"] == 400 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.APPLICATION_JSON] assert ( result["body"] == "{\"statusCode\":400,\"message\":\"Bad Request: Failed schema validation. Error: data must contain ['message'] properties, Path: ['data'], Data: {'username': 'lessa'}\"}" # noqa: E501 ) -def test_invalid_schema_validation(): - # GIVEN - app = ApiGatewayResolver() - +@pytest.mark.parametrize( + "app, event", + [ + ( + ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), + load_event("apigatewayeSchemaMiddlwareValidEvent.json"), + ), + ( + APIGatewayRestResolver(), + load_event("apigatewayeSchemaMiddlwareValidEvent.json"), + ), + ( + APIGatewayHttpResolver(), + load_event("apiGatewayProxyV2SchemaMiddlwareInvalidEvent.json"), + ), + ], +) +def test_invalid_schema_validation(app, event): @app.post("/my/path", middlewares=[SchemaValidationMiddleware(inbound_schema="schema.json")]) def post_lambda() -> Response: return Response(200, content_types.TEXT_HTML, "Should not be returned") # WHEN calling the event handler - result = app(load_event("apigatewayeSchemaMiddlwareValidEvent.json"), {}) + result = app(event, {}) print(f"\nRESULT:::{result}") # THEN assert result["statusCode"] == 500 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.APPLICATION_JSON] assert result["body"] == '{"statusCode":500,"message":"Internal Server Error"}' -def test_middleware_short_circuit_via_httperrors(): - # GIVEN - app = ApiGatewayResolver() - +@pytest.mark.parametrize( + "app, event", + [ + (ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), API_REST_EVENT), + (APIGatewayRestResolver(), API_REST_EVENT), + (APIGatewayHttpResolver(), API_RESTV2_EVENT), + ], +) +def test_middleware_short_circuit_via_httperrors(app, event): def middleware_one(app, get_response, **context): # inject a variable into the kwargs of the middleware chain response = get_response(app, injected="injected_value", **context) @@ -231,17 +291,23 @@ def get_lambda(my_id: str, name: str, injected: str) -> Response: return Response(200, content_types.TEXT_HTML, my_id) # WHEN calling the event handler - result = app(LOAD_GW_EVENT, {}) + result = app(event, {}) # THEN assert result["statusCode"] == 400 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.APPLICATION_JSON] assert result["body"] == '{"statusCode":400,"message":"bad_response"}' -def test_api_gateway_app_router_with_middlewares(): +@pytest.mark.parametrize( + "app, event", + [ + (ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), API_REST_EVENT), + (APIGatewayRestResolver(), API_REST_EVENT), + (APIGatewayHttpResolver(), API_RESTV2_EVENT), + ], +) +def test_api_gateway_app_router_with_middlewares(app, event): # GIVEN a Router with registered routes - app = ApiGatewayResolver() router = Router() def app_middleware(app, get_response, **context): @@ -279,9 +345,8 @@ def get_api_route(app_injected: str, router_injected: str, injected: str): app.include_router(router) # WHEN calling the event handler after applying routes from router object - result = app(LOAD_GW_EVENT, {}) + result = app(event, {}) # THEN process event correctly assert result["statusCode"] == 200 - assert result["multiValueHeaders"]["Content-Type"] == [content_types.TEXT_HTML] assert result["body"] == to_inject From af15705abf5920211703e31948c3afef1eb04f8a Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Thu, 31 Aug 2023 00:08:20 +1000 Subject: [PATCH 49/85] feat(middlewares): Additional Tests for route middleware, added debug, ensure Route.func is not overwritten by wrapped middleware stack - should always be the registered function. --- .../event_handler/api_gateway.py | 31 +++++-- tests/events/apiGatewayProxyOtherEvent.json | 81 +++++++++++++++++++ .../apiGatewayProxyV2OtherGetEvent.json | 68 ++++++++++++++++ .../event_handler/test_api_middlewares.py | 39 +++++++-- 4 files changed, 205 insertions(+), 14 deletions(-) create mode 100644 tests/events/apiGatewayProxyOtherEvent.json create mode 100644 tests/events/apiGatewayProxyV2OtherGetEvent.json diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index b385e32498b..a0d04e72dbb 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -244,6 +244,7 @@ def __init__( self.method = method.upper() self.rule = rule self.func = func + self._call_stack = func self.cors = cors self.compress = compress self.cache_control = cache_control @@ -288,8 +289,16 @@ def __call__( if not self._middleware_stack_built: self._build_middleware_stack(router_middlewares=router_middlewares) - # Call the Middleware Wrapped route function handler with the app and route arguments - return self.func(app, **route_arguments) + # If debug is turned on then output the middleware stack to the console + if app._debug: + all_middlewares = router_middlewares + self.middlewares + [_registered_api_adapter, self.func] + print("\nMiddleware Stack:") + print("=================") + 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) def _build_middleware_stack(self, router_middlewares: List[Callable]) -> None: """ @@ -329,7 +338,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.func = MiddlewareFrame(current_middleware=handler, next_middleware=self.func) + self._call_stack = MiddlewareFrame(current_middleware=handler, next_middleware=self._call_stack) self._middleware_stack_built = True @@ -430,7 +439,7 @@ class BaseRouter(ABC): lambda_context: LambdaContext context: dict _router_middlewares: List[Callable] = [] - _processed_stack_frames: List[str] = [] + processed_stack_frames: List[str] = [] @abstractmethod def route( @@ -645,11 +654,11 @@ def _push_processed_stack_frame(self, frame: str): The stack frames will be used when excpetions are thrown and Powertools debug is enabled by developers. """ - self._processed_stack_frames.append(frame) + self.processed_stack_frames.append(frame) def _reset_processed_stack(self): """Reset the Processed Stack Frames""" - self._processed_stack_frames = [] + self.processed_stack_frames = [] def append_context(self, **additional_context): """Append key=value data as routing context""" @@ -704,7 +713,7 @@ def __name__(self): # noqa: A003 def __str__(self) -> str: """Identify current middleware identity and call chain for debugging purposes.""" middleware_name = self.__name__ - return f"Middleware '{middleware_name}'. Next call chain is: {middleware_name} -> {self._next_middleware_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]: """ @@ -919,6 +928,14 @@ def resolve(self, event, context) -> Dict[str, Any]: BaseRouter.lambda_context = context response = self._resolve().build(self.current_event, self._cors) + + # Debug print Processed Middlewares + if self._debug: + print("\nProcessed Middlewares:") + print("======================") + print("\n".join(self.processed_stack_frames)) + print("======================") + self.clear_context() return response diff --git a/tests/events/apiGatewayProxyOtherEvent.json b/tests/events/apiGatewayProxyOtherEvent.json new file mode 100644 index 00000000000..5b9d09844ab --- /dev/null +++ b/tests/events/apiGatewayProxyOtherEvent.json @@ -0,0 +1,81 @@ +{ + "version": "1.0", + "resource": "/other/path", + "path": "/other/path", + "httpMethod": "GET", + "headers": { + "Header1": "value1", + "Header2": "value2", + "Origin": "https://aws.amazon.com" + }, + "multiValueHeaders": { + "Header1": [ + "value1" + ], + "Header2": [ + "value1", + "value2" + ] + }, + "queryStringParameters": { + "parameter1": "value1", + "parameter2": "value" + }, + "multiValueQueryStringParameters": { + "parameter1": [ + "value1", + "value2" + ], + "parameter2": [ + "value" + ] + }, + "requestContext": { + "accountId": "123456789012", + "apiId": "id", + "authorizer": { + "claims": null, + "scopes": null + }, + "domainName": "id.execute-api.us-east-1.amazonaws.com", + "domainPrefix": "id", + "extendedRequestId": "request-id", + "httpMethod": "GET", + "identity": { + "accessKey": null, + "accountId": null, + "caller": null, + "cognitoAuthenticationProvider": null, + "cognitoAuthenticationType": null, + "cognitoIdentityId": null, + "cognitoIdentityPoolId": null, + "principalOrgId": null, + "sourceIp": "192.168.0.1/32", + "user": null, + "userAgent": "user-agent", + "userArn": null, + "clientCert": { + "clientCertPem": "CERT_CONTENT", + "subjectDN": "www.example.com", + "issuerDN": "Example issuer", + "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", + "validity": { + "notBefore": "May 28 12:30:02 2019 GMT", + "notAfter": "Aug 5 09:36:04 2021 GMT" + } + } + }, + "path": "/other/path", + "protocol": "HTTP/1.1", + "requestId": "id=", + "requestTime": "04/Mar/2020:19:15:17 +0000", + "requestTimeEpoch": 1583349317135, + "resourceId": null, + "resourcePath": "/other/path", + "stage": "$default" + }, + "pathParameters": null, + "stageVariables": null, + "body": "Hello from Lambda!", + "isBase64Encoded": false +} diff --git a/tests/events/apiGatewayProxyV2OtherGetEvent.json b/tests/events/apiGatewayProxyV2OtherGetEvent.json new file mode 100644 index 00000000000..b9bd88f1c2e --- /dev/null +++ b/tests/events/apiGatewayProxyV2OtherGetEvent.json @@ -0,0 +1,68 @@ +{ + "version": "2.0", + "routeKey": "$default", + "rawPath": "/other/path", + "rawQueryString": "parameter1=value1¶meter1=value2¶meter2=value", + "cookies": [ + "cookie1", + "cookie2" + ], + "headers": { + "Header1": "value1", + "Header2": "value1,value2" + }, + "queryStringParameters": { + "parameter1": "value1,value2", + "parameter2": "value" + }, + "requestContext": { + "accountId": "123456789012", + "apiId": "api-id", + "authentication": { + "clientCert": { + "clientCertPem": "CERT_CONTENT", + "subjectDN": "www.example.com", + "issuerDN": "Example issuer", + "serialNumber": "a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1:a1", + "validity": { + "notBefore": "May 28 12:30:02 2019 GMT", + "notAfter": "Aug 5 09:36:04 2021 GMT" + } + } + }, + "authorizer": { + "jwt": { + "claims": { + "claim1": "value1", + "claim2": "value2" + }, + "scopes": [ + "scope1", + "scope2" + ] + } + }, + "domainName": "id.execute-api.us-east-1.amazonaws.com", + "domainPrefix": "id", + "http": { + "method": "GET", + "path": "/other/path", + "protocol": "HTTP/1.1", + "sourceIp": "192.168.0.1/32", + "userAgent": "agent" + }, + "requestId": "id", + "routeKey": "$default", + "stage": "$default", + "time": "12/Mar/2020:19:03:58 +0000", + "timeEpoch": 1583348638390 + }, + "pathParameters": { + "parameter1": "value1" + }, + "isBase64Encoded": false, + "stageVariables": { + "stageVariable1": "value1", + "stageVariable2": "value2" + } +} diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index 70dc5f7192e..8a79b2953b6 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -56,16 +56,28 @@ def get_lambda(another_one: int, custom: str) -> Response: @pytest.mark.parametrize( - "app, event", + "app, event, other_event", [ - (ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), API_REST_EVENT), - (APIGatewayRestResolver(), API_REST_EVENT), - (APIGatewayHttpResolver(), API_RESTV2_EVENT), + ( + ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), + API_REST_EVENT, + load_event("apiGatewayProxyOtherEvent.json"), + ), + ( + APIGatewayRestResolver(), + API_REST_EVENT, + load_event("apiGatewayProxyOtherEvent.json"), + ), + ( + APIGatewayHttpResolver(), + API_RESTV2_EVENT, + load_event("apiGatewayProxyV2OtherGetEvent.json"), + ), ], ) -def test_with_router_middleware(app, event): +def test_with_router_middleware(app, event, other_event): # define custom middleware to inject new argument - "custom" - def middleware_1(app, get_response, **kwargs): + def global_middleware(app, get_response, **kwargs): # inject a variable into the kwargs response = get_response(app, custom="custom", **kwargs) @@ -78,7 +90,7 @@ def middleware_2(app, get_response, **kwargs): return response - app.use([middleware_1]) + app.use([global_middleware]) @app.get("/my/path", middlewares=[middleware_2]) def get_lambda(another_one: int, custom: str) -> Response: @@ -94,6 +106,19 @@ def get_lambda(another_one: int, custom: str) -> Response: assert result["statusCode"] == 200 assert result["body"] == "foo" + @app.get("/other/path") + def get_other_lambda(custom: str) -> Response: + assert custom == "custom" + return Response(200, content_types.TEXT_HTML, "other_foo") + + # WHEN calling the event handler + result = app(other_event, {}) + + # THEN process event correctly + # AND set the current_event type as APIGatewayProxyEvent + assert result["statusCode"] == 200 + assert result["body"] == "other_foo" + @pytest.mark.parametrize( "app, event", From bf439e432d500c9dd0a4070bbd90f5bc927d0d52 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Thu, 31 Aug 2023 00:26:02 +1000 Subject: [PATCH 50/85] feat(middlewares): Tidy up config, add additional context for _path for the matched API route path --- aws_lambda_powertools/event_handler/api_gateway.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index a0d04e72dbb..d93a87365da 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -291,7 +291,9 @@ def __call__( # If debug is turned on then output the middleware stack to the console if app._debug: - all_middlewares = router_middlewares + self.middlewares + [_registered_api_adapter, self.func] + print(f"\nProcessing Route:::{self.func.__name__} ({app.context['_path']})") + # Collect ALL middleware for debug printing - include internal _registered_api_adapter + all_middlewares = router_middlewares + self.middlewares + [_registered_api_adapter] print("\nMiddleware Stack:") print("=================") print("\n".join(getattr(item, "__name__", "Unknown") for item in all_middlewares)) @@ -1012,6 +1014,10 @@ def _resolve(self) -> ResponseBuilder: match_results: Optional[Match] = route.rule.match(path) if match_results: logger.debug("Found a registered route. Calling function") + # Add matched Route reference into the Resolver context + self.append_context(_route=route) + self.append_context(_path=path) + return self._call_route(route, match_results.groupdict()) # pass fn args logger.debug(f"No match found for path {path} and method {method}") @@ -1080,9 +1086,6 @@ def _call_route(self, route: Route, route_arguments: Dict[str, str]) -> Response # Reset Processed stack for Middleware (for debugging purposes) self._reset_processed_stack() - # Add matched Route reference into the Resolver context - self.append_context(_route=route) - return ResponseBuilder( self._to_response( route(router_middlewares=self._router_middlewares, app=self, route_arguments=route_arguments), From 9fb4c6f2f43c1066abffad518eab25d61f32a7dc Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Fri, 1 Sep 2023 21:09:42 +1000 Subject: [PATCH 51/85] chore(docs): updated imges to be svg for middlewares from draw.io - light/dark and added to docs --- docs/core/event_handler/api_gateway.md | 34 +- docs/diagram_src/.$api-middlewares.drawio.bkp | 1193 ++++++-- docs/diagram_src/api-middlewares.drawio | 2469 ++++++++++------- .../middlewares_catch_exception-dark.svg | 4 + .../middlewares_catch_exception-light.svg | 4 + ...middlewares_catch_route_exception-dark.svg | 4 + ...iddlewares_catch_route_exception-light.svg | 4 + docs/media/middlewares_early_return-dark.svg | 4 + docs/media/middlewares_early_return-light.svg | 4 + .../middlewares_normal_processing-dark.svg | 4 + .../middlewares_normal_processing-light.svg | 4 + docs/media/middlewares_normal_processing.svg | 3 - .../middlewares_unhandled_exception-dark.svg | 4 + .../middlewares_unhandled_exception-light.svg | 4 + ...lewares_unhandled_route_exception-dark.svg | 4 + ...ewares_unhandled_route_exception-light.svg | 4 + 16 files changed, 2509 insertions(+), 1238 deletions(-) create mode 100644 docs/media/middlewares_catch_exception-dark.svg create mode 100644 docs/media/middlewares_catch_exception-light.svg create mode 100644 docs/media/middlewares_catch_route_exception-dark.svg create mode 100644 docs/media/middlewares_catch_route_exception-light.svg create mode 100644 docs/media/middlewares_early_return-dark.svg create mode 100644 docs/media/middlewares_early_return-light.svg create mode 100644 docs/media/middlewares_normal_processing-dark.svg create mode 100644 docs/media/middlewares_normal_processing-light.svg delete mode 100644 docs/media/middlewares_normal_processing.svg create mode 100644 docs/media/middlewares_unhandled_exception-dark.svg create mode 100644 docs/media/middlewares_unhandled_exception-light.svg create mode 100644 docs/media/middlewares_unhandled_route_exception-dark.svg create mode 100644 docs/media/middlewares_unhandled_route_exception-light.svg diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 5c8afd72423..c7febb64790 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -420,7 +420,8 @@ Here's a sample middleware that extracts and injects correlation ID, using `APIG #### Global middlewares
-![Combining middlewares](../../media/middlewares_normal_processing.svg) +![Combining middlewares](../../media/middlewares_normal_processing-light.svg#only-light) +![Combining middlewares](../../media/middlewares_normal_processing-dark.svg#only-dark) _Request flowing through multiple registered middlewares_
@@ -459,7 +460,8 @@ Event Handler **calls global middlewares first**, then middlewares defined at th #### Returning early
-![Short-circuiting middleware chain](../../media/middlewares_early_return.svg) +![Short-circuiting middleware chain](../../media/middlewares_early_return-light.svg#only-light) +![Short-circuiting middleware chain](../../media/middlewares_early_return-dark.svg#only-dark) _Interrupting request flow by returning early_
@@ -520,9 +522,35 @@ Here's an example where we now prevent any request that doesn't include a correl ???+ warning "Ensure your middleware returns the Next Response" Your middleware functions must return the response from calling **get_response** or a modified version of the Response. If you do not return a value your API route will not work and return an API gateway error. +#### More images (light and dark) + +
+![Short-circuiting middleware chain](../../media/middlewares_unhandled_exception-light.svg#only-light) +![Short-circuiting middleware chain](../../media/middlewares_unhandled_exception-dark.svg#only-dark) +_Interrupting request flow by raising an unhandled exception_ +
+ +
+![Short-circuiting middleware chain](../../media/middlewares_catch_exception-light.svg#only-light) +![Short-circuiting middleware chain](../../media/middlewares_catch_exception-dark.svg#only-dark) +_Interrupting request flow by raising an exception captured by Middleware_ +
+ +
+![Short-circuiting middleware chain](../../media/middlewares_unhandled_route_exception-light.svg#only-light) +![Short-circuiting middleware chain](../../media/middlewares_unhandled_route_exception-dark.svg#only-dark) +_Unhandled exception from route handler_ +
+ +
+![Short-circuiting middleware chain](../../media/middlewares_catch_route_exception-light.svg#only-light) +![Short-circuiting middleware chain](../../media/middlewares_catch_route_exception-dark.svg#only-dark) +_Unhandled exception from route handler captured by Middleware_ +
+ **This should go under the Router area since we haven't introduced it yet** -Middleware functions used in the Router instance will apply to all API routes and will always be processed first in the order they are added to the Router. Route specific middleware added to each route will then be processed in the order they were added in the route defintion. +Middleware functions used in the Router instance will apply to all API routes and will always be processed first in the order they are added to the Router. Route specific middleware added to each route will then be processed in the order they were added in the route definition. ???+ tip **Router Middleware processing Order** diff --git a/docs/diagram_src/.$api-middlewares.drawio.bkp b/docs/diagram_src/.$api-middlewares.drawio.bkp index 93500c7a13a..5f82484fb87 100644 --- a/docs/diagram_src/.$api-middlewares.drawio.bkp +++ b/docs/diagram_src/.$api-middlewares.drawio.bkp @@ -1,4 +1,4 @@ - + @@ -7,7 +7,7 @@ - + @@ -66,14 +66,14 @@ - + - + @@ -183,7 +183,7 @@ - + @@ -191,7 +191,7 @@ - + @@ -231,19 +231,7 @@ - - - - - - - - - - - - - + @@ -258,7 +246,7 @@ - + @@ -273,7 +261,7 @@ - + @@ -288,125 +276,176 @@ - + - - + + + + + + + + + + + - - + + - - - + + + - + - + - + - - + + - + - - + + - + + + + + + + + + - + + + + - - + + - - + + - + - + - + - - - - - + + - - + + - + - + - + - - - - - + + - - + + - + - + - + - - - - - + + - - + + - + - + - + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - + - + @@ -420,114 +459,204 @@ - + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + - - - + + + - + - + - + - - + + + + + + + + + + - - + + - - + + - - + + + + + - - + + + + + - - + + + + - - + + - - + + - - + + - + - + - + - - + + - - + + - - + + - + - + - + - - + + - - + + - - + + - - + + - - + + - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - + + - + - + @@ -550,177 +679,439 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + + + + + + + + + - - + + - - + + - - + + - + - + - + - - + - + - + - + - + - - + + - + - - + + - - - - + + - - + + - - - - - - - - - - + + - - + + - - + + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -757,7 +1148,7 @@ - + @@ -772,7 +1163,7 @@ - + @@ -787,7 +1178,7 @@ - + @@ -802,101 +1193,176 @@ - + - - - - + + + + - - + + - - - + + + - + - + - + - + - + - + - - - + + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -911,12 +1377,9 @@ - + - - - @@ -929,6 +1392,142 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/diagram_src/api-middlewares.drawio b/docs/diagram_src/api-middlewares.drawio index e76cb313714..9a3c68901bd 100644 --- a/docs/diagram_src/api-middlewares.drawio +++ b/docs/diagram_src/api-middlewares.drawio @@ -1,935 +1,1534 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/media/middlewares_catch_exception-dark.svg b/docs/media/middlewares_catch_exception-dark.svg new file mode 100644 index 00000000000..558f54652d5 --- /dev/null +++ b/docs/media/middlewares_catch_exception-dark.svg @@ -0,0 +1,4 @@ + + + +
Event
Handler
Event...
API Route
Handler
API Route...
Short-Circuited via Exception
from Middleware-3
Short-Circuited via Exception...
After processing for
Middleware-1 only
After processing for...

Response from
Middleware-1
Response from...
@app.get("/todos")
@app.get("/todos")
Middleware-1
Middleware-1
Middleware-2
Middleware-2
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
Middleware-4 and API Route Handler were not called due to an exception in the previous step
Middleware-4 and API Route Handler were...
Before
Before
After
After
Next (Catch Exceptions)
Next (Catch E...
Before
Before
After
After
Next
Next
Before
Before
After
After
Next
Next
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/media/middlewares_catch_exception-light.svg b/docs/media/middlewares_catch_exception-light.svg new file mode 100644 index 00000000000..37fd79ad075 --- /dev/null +++ b/docs/media/middlewares_catch_exception-light.svg @@ -0,0 +1,4 @@ + + + +
Event
Handler
Event...
API Route
Handler
API Route...
Short-Circuited via Exception
from Middleware-3
Short-Circuited via Exception...
After processing for
Middleware-1 only
After processing for...

Response from
Middleware-1
Response from...
@app.get("/todos")
@app.get("/todos")
Middleware-1
Middleware-1
Middleware-2
Middleware-2
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
Middleware-4 and API Route Handler were not called due to an exception in the previous step
Middleware-4 and API Route Handler were...
Before
Before
After
After
Next (Catch Exceptions)
Next (Catch E...
Before
Before
After
After
Next
Next
Before
Before
After
After
Next
Next
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/media/middlewares_catch_route_exception-dark.svg b/docs/media/middlewares_catch_route_exception-dark.svg new file mode 100644 index 00000000000..be51e7f8de4 --- /dev/null +++ b/docs/media/middlewares_catch_route_exception-dark.svg @@ -0,0 +1,4 @@ + + + +
Next
Next
Event
Handler
Event...
API Route
Handler
API Route...
Middleware-1
Middleware-1
Middleware-2
Middleware-2
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
Call stack unwinds to first try..except block within middleware
Middleware-3 returns normal response which is also processed
by Middleware-2 and Middleware-1 after processing
Call stack unwinds to first try..except block within middleware...
@app.get("/todos")
@app.get("/todos")
Before
Before
After
After
Before
Before
After
After
Next
Next
Before
Before
After
After
Next (Catch Exceptions)
Next (Catch E...
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/media/middlewares_catch_route_exception-light.svg b/docs/media/middlewares_catch_route_exception-light.svg new file mode 100644 index 00000000000..70787b489af --- /dev/null +++ b/docs/media/middlewares_catch_route_exception-light.svg @@ -0,0 +1,4 @@ + + + +
Next
Next
Event
Handler
Event...
API Route
Handler
API Route...
Middleware-1
Middleware-1
Middleware-2
Middleware-2
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
Call stack unwinds to first try..except block within middleware
Middleware-3 returns normal response which is also processed
by Middleware-2 and Middleware-1 after processing
Call stack unwinds to first try..except block within middleware...
@app.get("/todos")
@app.get("/todos")
Before
Before
After
After
Before
Before
After
After
Next
Next
Before
Before
After
After
Next (Catch Exceptions)
Next (Catch E...
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/media/middlewares_early_return-dark.svg b/docs/media/middlewares_early_return-dark.svg new file mode 100644 index 00000000000..3a99cb1a221 --- /dev/null +++ b/docs/media/middlewares_early_return-dark.svg @@ -0,0 +1,4 @@ + + + +
Event
Handler
Event...
API Route
Handler
API Route...
Short-Circuited Response from Middleware-3
Short-Circuited Response from Middleware-3
Middleware-4 and API Route Handler not called due to early
return in previous step
Middleware-4 and API Route Handler not c...
After Middleware processing occurs for
Middleware-2 and Middleware-1 (in that order)
After Middleware processing occurs for...
Before
Before
After
After
Next
Next
Middleware-3
Middleware-3
Middleware-4
Middleware-4
Before
Before
After
After
Next
Next
Middleware-2
Middleware-2
Middleware-1
Middleware-1
Before
Before
After
After
Next
Next
Before
Before
After
After
Next
Next
@app.get("/todos")
@app.get("/todos")
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/media/middlewares_early_return-light.svg b/docs/media/middlewares_early_return-light.svg new file mode 100644 index 00000000000..01b01268c7c --- /dev/null +++ b/docs/media/middlewares_early_return-light.svg @@ -0,0 +1,4 @@ + + + +
Event
Handler
Event...
API Route
Handler
API Route...
Short-Circuited Response from Middleware-3
Short-Circuited Response from Middleware-3
Middleware-4 and API Route Handler not called due to early
return in previous step
Middleware-4 and API Route Handler not c...
After Middleware processing occurs for
Middleware-2 and Middleware-1 (in that order)
After Middleware processing occurs for...
Middleware-1
Middleware-1
Middleware-3
Middleware-3
Middleware-4
Middleware-4
Before
Before
After
After
Next
Next
Before
Before
After
After
Next
Next
Middleware-2
Middleware-2
Before
Before
After
After
Next
Next
@app.get("/todos")
@app.get("/todos")
Before
Before
After
After
Next
Next
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/media/middlewares_normal_processing-dark.svg b/docs/media/middlewares_normal_processing-dark.svg new file mode 100644 index 00000000000..9e8cc8662b9 --- /dev/null +++ b/docs/media/middlewares_normal_processing-dark.svg @@ -0,0 +1,4 @@ + + + +
Event
Handler
Event...
API Route
Handler
API Route...
Before
Before
After
After
Next
Next
Middleware-1
Middleware-1
Before
Before
After
After
Next
Next
Middleware-2
Middleware-2
Before
Before
After
After
Next
Next
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
@app.get("/todos")
@app.get("/todos")
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/media/middlewares_normal_processing-light.svg b/docs/media/middlewares_normal_processing-light.svg new file mode 100644 index 00000000000..62c5368c7e8 --- /dev/null +++ b/docs/media/middlewares_normal_processing-light.svg @@ -0,0 +1,4 @@ + + + +
Event
Handler
Event...
API Route
Handler
API Route...
Middleware-1
Middleware-1
Before
Before
After
After
Next
Next
Middleware-2
Middleware-2
Before
Before
After
After
Next
Next
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
@app.get("/todos")
@app.get("/todos")
Before
Before
After
After
Next
Next
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/media/middlewares_normal_processing.svg b/docs/media/middlewares_normal_processing.svg deleted file mode 100644 index 52b1f4cca83..00000000000 --- a/docs/media/middlewares_normal_processing.svg +++ /dev/null @@ -1,3 +0,0 @@ - - -
Event
Handler
Event<br>Handler
API Route
Handler
API Route<br>Handler
Before
Before
After
After
Next
Next
Middleware-1
Middleware-1
Before
Before
After
After
Next
Next
Middleware-2
Middleware-2
Before
Before
After
After
Next
Next
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
@app.get("/todos")
@app.get("/todos")
\ No newline at end of file diff --git a/docs/media/middlewares_unhandled_exception-dark.svg b/docs/media/middlewares_unhandled_exception-dark.svg new file mode 100644 index 00000000000..9278db86fa0 --- /dev/null +++ b/docs/media/middlewares_unhandled_exception-dark.svg @@ -0,0 +1,4 @@ + + + +
Event
Handler
Event...
Short-Circuited from Middleware-3 via an Exception
Short-Circuited from Middleware-3 via an Exception
No other Middleware "after" components will be processed
unless exception is captured from next() call.
No other Middleware "after" components will be processed...
Middleware-4 and API Route Handler were not called due to an exception in the previous step
Middleware-4 and API Route Handler were...

Middleware-1
Middleware-1
Middleware-2
Middleware-2
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
API Route
Handler
API Route...
@app.get("/todos")
@app.get("/todos")
Before
Before
After
After
Next
Next
Before
Before
After
After
Next
Next
Before
Before
After
After
Next
Next
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/media/middlewares_unhandled_exception-light.svg b/docs/media/middlewares_unhandled_exception-light.svg new file mode 100644 index 00000000000..b9377109916 --- /dev/null +++ b/docs/media/middlewares_unhandled_exception-light.svg @@ -0,0 +1,4 @@ + + + +
Event
Handler
Event...
Short-Circuited from Middleware-3 via an Exception
Short-Circuited from Middleware-3 via an Exception
No other Middleware "after" components will be processed
unless exception is captured from next() call.
No other Middleware "after" components will be processed...

Middleware-1
Middleware-1
Middleware-2
Middleware-2
Middleware-3
Middleware-3
Middleware-4
Middleware-4
Before
Before
After
After
Next
Next
Before
Before
After
After
Next
Next
Before
Before
After
After
Next
Next
Before
Before
After
After
Next
Next
API Route
Handler
API Route...
@app.get("/todos")
@app.get("/todos")
Middleware-4 and API Route Handler were not called due to an exception in the previous step
Middleware-4 and API Route Handler were...
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/media/middlewares_unhandled_route_exception-dark.svg b/docs/media/middlewares_unhandled_route_exception-dark.svg new file mode 100644 index 00000000000..fc68c7a97c0 --- /dev/null +++ b/docs/media/middlewares_unhandled_route_exception-dark.svg @@ -0,0 +1,4 @@ + + + +
Next
Next
Event
Handler
Event...
API Route
Handler
API Route...
Before
Before
After
After
Middleware-1
Middleware-1
Before
Before
After
After
Next
Next
Middleware-2
Middleware-2
Before
Before
After
After
Next
Next
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
Call stack unwinds to Event Handler after it has been captured and handled by Powertools
Call stack unwinds to Event Handler after it has been captured and handled by Powertools
@app.get("/todos")
@app.get("/todos")
Text is not SVG - cannot display
\ No newline at end of file diff --git a/docs/media/middlewares_unhandled_route_exception-light.svg b/docs/media/middlewares_unhandled_route_exception-light.svg new file mode 100644 index 00000000000..0beba842a69 --- /dev/null +++ b/docs/media/middlewares_unhandled_route_exception-light.svg @@ -0,0 +1,4 @@ + + + +
Next
Next
Event
Handler
Event...
API Route
Handler
API Route...
Before
Before
After
After
Middleware-1
Middleware-1
Before
Before
After
After
Next
Next
Middleware-2
Middleware-2
Before
Before
After
After
Next
Next
Middleware-3
Middleware-3
Before
Before
After
After
Next
Next
Middleware-4
Middleware-4
Call stack unwinds to Event Handler after it has been captured and handled by Powertools
Call stack unwinds to Event Handler after it has been captured and handled by Powertools
@app.get("/todos")
@app.get("/todos")
Text is not SVG - cannot display
\ No newline at end of file From 06b1d90a3374bc3abd4b0f6362d64ccf4b016ed6 Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Sat, 2 Sep 2023 17:34:07 +1000 Subject: [PATCH 52/85] chore(example): fix custom middleware example to correct raise of captured exception and raise new exception from original --- examples/event_handler_rest/src/custom_middlewares.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/examples/event_handler_rest/src/custom_middlewares.py b/examples/event_handler_rest/src/custom_middlewares.py index ce260f08978..992d57abf77 100644 --- a/examples/event_handler_rest/src/custom_middlewares.py +++ b/examples/event_handler_rest/src/custom_middlewares.py @@ -24,7 +24,9 @@ def sanitise_exceptions(app: ApiGatewayResolver, get_response: Callable[..., Any logger.exception(err) # Raise a clean error for ALL unexpected exceptions (ServiceError based Exceptions are okay) if not isinstance(err, ServiceError): - raise InternalServerError("An error occurred during processing, please contact your administrator") + raise InternalServerError("An error occurred during processing, please contact your administrator") from err + + raise err # return the result when there are no exceptions return result From 61022be22203e1cf88183303b8904870eeb5ebd0 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Sat, 2 Sep 2023 17:48:25 +0200 Subject: [PATCH 53/85] chore: type middleware callback Signed-off-by: heitorlessa --- aws_lambda_powertools/event_handler/api_gateway.py | 7 +++++++ aws_lambda_powertools/event_handler/types.py | 3 +++ aws_lambda_powertools/shared/types.py | 9 +++++++++ examples/event_handler_rest/src/custom_middlewares.py | 9 ++++----- .../src/middleware_global_middlewares_module.py | 9 ++++----- 5 files changed, 27 insertions(+), 10 deletions(-) create mode 100644 aws_lambda_powertools/event_handler/types.py diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 6663c76cba8..e140093317c 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -28,6 +28,7 @@ from aws_lambda_powertools.shared.cookies import Cookie from aws_lambda_powertools.shared.functions import powertools_dev_is_set from aws_lambda_powertools.shared.json_encoder import Encoder +from aws_lambda_powertools.shared.types import Protocol from aws_lambda_powertools.utilities.data_classes import ( ALBEvent, APIGatewayProxyEvent, @@ -1326,3 +1327,9 @@ def __init__( ): """Amazon Application Load Balancer (ALB) resolver""" super().__init__(ProxyEventType.ALBEvent, cors, debug, serializer, strip_prefixes) + + +class NextMiddlewareCallback(Protocol): + def __call__(self, app: ApiGatewayResolver, **kwds: Any) -> Response: + """Protocol for callback regardless of get_response(app, **kwargs), next(app, **kwargs)""" + ... diff --git a/aws_lambda_powertools/event_handler/types.py b/aws_lambda_powertools/event_handler/types.py new file mode 100644 index 00000000000..d584549f95d --- /dev/null +++ b/aws_lambda_powertools/event_handler/types.py @@ -0,0 +1,3 @@ +from aws_lambda_powertools.event_handler.api_gateway import NextMiddlewareCallback + +__all__ = ["NextMiddlewareCallback"] diff --git a/aws_lambda_powertools/shared/types.py b/aws_lambda_powertools/shared/types.py index e4e10192e55..b29c04cbe6b 100644 --- a/aws_lambda_powertools/shared/types.py +++ b/aws_lambda_powertools/shared/types.py @@ -1,5 +1,14 @@ +import sys from typing import Any, Callable, Dict, List, TypeVar, Union AnyCallableT = TypeVar("AnyCallableT", bound=Callable[..., Any]) # noqa: VNE001 # JSON primitives only, mypy doesn't support recursive tho JSONType = Union[str, int, float, bool, None, Dict[str, Any], List[Any]] + + +if sys.version_info >= (3, 8): + from typing import Protocol +else: + from typing_extensions import Protocol + +__all__ = ["Protocol"] diff --git a/examples/event_handler_rest/src/custom_middlewares.py b/examples/event_handler_rest/src/custom_middlewares.py index 992d57abf77..7fdcb83a1d0 100644 --- a/examples/event_handler_rest/src/custom_middlewares.py +++ b/examples/event_handler_rest/src/custom_middlewares.py @@ -1,13 +1,12 @@ -from typing import Any, Callable - from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import ApiGatewayResolver, Response +from aws_lambda_powertools.event_handler.api_gateway import NextMiddlewareCallback from aws_lambda_powertools.event_handler.exceptions import BadRequestError, InternalServerError, ServiceError logger = Logger() -def validate_correlation_id(app: ApiGatewayResolver, get_response: Callable[..., Any], **context_args) -> Response: +def validate_correlation_id(app: ApiGatewayResolver, get_response: NextMiddlewareCallback, **context_args) -> 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.") @@ -16,10 +15,10 @@ def validate_correlation_id(app: ApiGatewayResolver, get_response: Callable[..., return get_response(app, **context_args) -def sanitise_exceptions(app: ApiGatewayResolver, get_response: Callable[..., Any], **context_args) -> Response: +def sanitise_exceptions(app: ApiGatewayResolver, get_response: NextMiddlewareCallback, **context_args) -> Response: try: # Get the Result from the next middleware - result: Response = get_response(app, **context_args) + result = get_response(app, **context_args) except Exception as err: logger.exception(err) # Raise a clean error for ALL unexpected exceptions (ServiceError based Exceptions are okay) diff --git a/examples/event_handler_rest/src/middleware_global_middlewares_module.py b/examples/event_handler_rest/src/middleware_global_middlewares_module.py index a0fbad53be1..9a69e95db55 100644 --- a/examples/event_handler_rest/src/middleware_global_middlewares_module.py +++ b/examples/event_handler_rest/src/middleware_global_middlewares_module.py @@ -1,13 +1,12 @@ -from typing import Callable - from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response from aws_lambda_powertools.event_handler.exceptions import BadRequestError +from aws_lambda_powertools.event_handler.types import NextMiddlewareCallback logger = Logger() -def log_request_response(app: APIGatewayRestResolver, get_response: Callable[..., Response], **context) -> Response: +def log_request_response(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **context) -> Response: logger.info("Incoming request", path=app.current_event.path, request=app.current_event.raw_event) result = get_response(app, **context) @@ -16,7 +15,7 @@ def log_request_response(app: APIGatewayRestResolver, get_response: Callable[... return result -def inject_correlation_id(app: APIGatewayRestResolver, get_response: Callable[..., Response], **context) -> Response: +def inject_correlation_id(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **context) -> 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 @@ -34,7 +33,7 @@ def inject_correlation_id(app: APIGatewayRestResolver, get_response: Callable[.. return result -def enforce_correlation_id(app: APIGatewayRestResolver, get_response: Callable[..., Response], **context) -> Response: +def enforce_correlation_id(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **context) -> Response: # If missing mandatory header raise an error if not app.current_event.get_header_value("x-correlation-id", case_sensitive=False): raise BadRequestError("Correlation ID header is now mandatory.") # (1)! From 21af5976d77a85611e7d3294b883bec657266eb0 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Sat, 2 Sep 2023 17:59:06 +0200 Subject: [PATCH 54/85] chore: type middleware response Signed-off-by: heitorlessa --- aws_lambda_powertools/event_handler/api_gateway.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index e140093317c..9c90c17f0cd 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -456,7 +456,7 @@ def route( ): raise NotImplementedError() - def use(self, middlewares: List[Callable[..., Any]]) -> None: + def use(self, middlewares: List[Callable[..., Response]]) -> None: """ Add a list of middlewares to the global router middleware list @@ -465,7 +465,7 @@ def use(self, middlewares: List[Callable[..., Any]]) -> None: Example ------- - Add middlewares to be used for every reuqest processed by the Router. + Add middlewares to be used for every request processed by the Router. ``` my_custom_middleware = new CustomMiddleware() From 0ca6683b8277905be8bdf534d63c5582d05d9a08 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Sat, 2 Sep 2023 18:32:20 +0200 Subject: [PATCH 55/85] docs: improve early return; use kwargs over ctx --- docs/core/event_handler/api_gateway.md | 14 ++++++++------ .../src/middleware_early_return_output.json | 8 ++------ .../src/middleware_getting_started.py | 7 +++---- .../src/middleware_global_middlewares_module.py | 15 +++++++-------- 4 files changed, 20 insertions(+), 24 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index c7febb64790..4d3ff2feef3 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -395,13 +395,13 @@ Each middleware function receives the following arguments: 1. **app**. An Event Handler instance so you can access incoming request information, Lambda context, etc. 2. **get_response**. A function to get the next middleware or route's response. -3. **`**context`**. A Middleware context that is propagated with dynamic route arguments and any previously injected metadata. +3. **`**kwargs`**. Middleware keyword arguments that are propagated in the chain. Here's a sample middleware that extracts and injects correlation ID, using `APIGatewayRestResolver` (works for any [Resolver](#event-resolvers)): === "middleware_getting_started.py" - ```python hl_lines="12 23 30" title="Your first middleware to extract and inject correlation ID" + ```python hl_lines="11 22 29" title="Your first middleware to extract and inject correlation ID" --8<-- "examples/event_handler_rest/src/middleware_getting_started.py" ``` @@ -422,6 +422,7 @@ Here's a sample middleware that extracts and injects correlation ID, using `APIG
![Combining middlewares](../../media/middlewares_normal_processing-light.svg#only-light) ![Combining middlewares](../../media/middlewares_normal_processing-dark.svg#only-dark) + _Request flowing through multiple registered middlewares_
@@ -453,7 +454,7 @@ Event Handler **calls global middlewares first**, then middlewares defined at th === "middleware_global_middlewares_module.py" - ```python hl_lines="10" + ```python hl_lines="9" --8<-- "examples/event_handler_rest/src/middleware_global_middlewares_module.py" ``` @@ -462,14 +463,15 @@ Event Handler **calls global middlewares first**, then middlewares defined at th
![Short-circuiting middleware chain](../../media/middlewares_early_return-light.svg#only-light) ![Short-circuiting middleware chain](../../media/middlewares_early_return-dark.svg#only-dark) + _Interrupting request flow by returning early_
Imagine you want to stop processing a request if something is missing, or return immediately if you've seen this request before. -In these scenarios, you short-circuit the middleware processing logic by raising a [HTTP Error](#raising-http-errors), or returning a [Response object](#fine-grained-responses). Event Handler will understand it now needs to run each “After” logic left in the chain. +In these scenarios, you short-circuit the middleware processing logic by returning a [Response object](#fine-grained-responses), or raising a [HTTP Error](#raising-http-errors). This signals to Event Handler to stop and run each `After` logic left in the chain all the way back. -Here's an example where we now prevent any request that doesn't include a correlation ID header: +Here's an example where we prevent any request that doesn't include a correlation ID header: === "middleware_early_return.py" @@ -482,7 +484,7 @@ Here's an example where we now prevent any request that doesn't include a correl === "middleware_global_middlewares_module.py" - ```python hl_lines="37 40" + ```python hl_lines="35 38" --8<-- "examples/event_handler_rest/src/middleware_global_middlewares_module.py" ``` diff --git a/examples/event_handler_rest/src/middleware_early_return_output.json b/examples/event_handler_rest/src/middleware_early_return_output.json index 16299f2cfd7..850b63764de 100644 --- a/examples/event_handler_rest/src/middleware_early_return_output.json +++ b/examples/event_handler_rest/src/middleware_early_return_output.json @@ -1,10 +1,6 @@ { "statusCode": 400, - "body": "{'statusCode':400,'message':'Correlation ID header is now mandatory.'}", + "body": "Correlation ID header is now mandatory", "isBase64Encoded": false, - "multiValueHeaders": { - "Content-Type": [ - "application/json" - ] - } + "multiValueHeaders": {} } \ No newline at end of file diff --git a/examples/event_handler_rest/src/middleware_getting_started.py b/examples/event_handler_rest/src/middleware_getting_started.py index d5d06090201..b8a8014ce4e 100644 --- a/examples/event_handler_rest/src/middleware_getting_started.py +++ b/examples/event_handler_rest/src/middleware_getting_started.py @@ -1,15 +1,14 @@ -from typing import Callable - import requests from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response +from aws_lambda_powertools.event_handler.types import NextMiddlewareCallback app = APIGatewayRestResolver() logger = Logger() -def inject_correlation_id(app: APIGatewayRestResolver, get_response: Callable[..., Response], **context) -> Response: +def inject_correlation_id(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **kwargs) -> 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 @@ -20,7 +19,7 @@ def inject_correlation_id(app: APIGatewayRestResolver, get_response: Callable[.. logger.set_correlation_id(request_id) # Get response from next middleware OR /todos route - result = get_response(app, **context) # (3)! + result = get_response(app, **kwargs) # (3)! # Include Correlation ID in the response back to caller result.headers["x-correlation-id"] = correlation_id # (4)! diff --git a/examples/event_handler_rest/src/middleware_global_middlewares_module.py b/examples/event_handler_rest/src/middleware_global_middlewares_module.py index 9a69e95db55..3f1d9e12b2f 100644 --- a/examples/event_handler_rest/src/middleware_global_middlewares_module.py +++ b/examples/event_handler_rest/src/middleware_global_middlewares_module.py @@ -1,21 +1,20 @@ from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response -from aws_lambda_powertools.event_handler.exceptions import BadRequestError from aws_lambda_powertools.event_handler.types import NextMiddlewareCallback logger = Logger() -def log_request_response(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **context) -> Response: +def log_request_response(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **kwargs) -> Response: logger.info("Incoming request", path=app.current_event.path, request=app.current_event.raw_event) - result = get_response(app, **context) + result = get_response(app, **kwargs) logger.info("Response received", response=result.__dict__) return result -def inject_correlation_id(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **context) -> Response: +def inject_correlation_id(app: APIGatewayRestResolver, get_response: 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 @@ -26,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, **context) + result = get_response(app, **kwargs) # 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, **context) -> Response: +def enforce_correlation_id(app: APIGatewayRestResolver, get_response: NextMiddlewareCallback, **kwargs) -> Response: # If missing mandatory header raise an error if not app.current_event.get_header_value("x-correlation-id", case_sensitive=False): - raise BadRequestError("Correlation ID header is now mandatory.") # (1)! + 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, **context) + return get_response(app, **kwargs) From 9704939020d6bcb4186ff98a970d146fe8255e5a Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Sat, 2 Sep 2023 20:16:27 +0200 Subject: [PATCH 56/85] docs: add handling exceptions section --- docs/core/event_handler/api_gateway.md | 43 +- docs/diagram_src/api-middlewares.drawio | 3068 +++++++++++------------ 2 files changed, 1576 insertions(+), 1535 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 4d3ff2feef3..e80795294d2 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -461,7 +461,7 @@ Event Handler **calls global middlewares first**, then middlewares defined at th #### Returning early
-![Short-circuiting middleware chain](../../media/middlewares_early_return-light.svg#only-light) +![Short-circuiting middleware chain](../../medi/middlewares_early_return-light.svg#only-light) ![Short-circuiting middleware chain](../../media/middlewares_early_return-dark.svg#only-dark) _Interrupting request flow by returning early_ @@ -496,6 +496,47 @@ Here's an example where we prevent any request that doesn't include a correlatio --8<-- "examples/event_handler_rest/src/middleware_early_return_output.json" ``` +#### Handling exceptions + +!!! tip "For catching exceptions more broadly, we recommend you use the [exception_handler](#exception-handling) decorator." + +By default, any unhandled exception in the middleware chain is eventually propagated as a HTTP 500 back to the client. + +While there isn't anything special on how to use [`try/catch`](https://docs.python.org/3/tutorial/errors.html#handling-exceptions){target="_blank" rel="nofollow"} for middlewares, it is important to visualize how Event Handler deals with them under the following scenarios: + +=== "Unhandled exception from route handler" + + An exception wasn't caught by any middleware during `get_response()` block, therefore it propagates all the way back to the client as HTTP 500. + +
+ ![Unhandled exceptions](../../media/middlewares_unhandled_route_exception-light.svg#only-light) + ![Unhandled exceptions](../../media/middlewares_unhandled_route_exception-dark.svg#only-dark) + + _Unhandled route exceptions propagate back to the client_ +
+ +=== "Route handler exception caught by a middleware" + + An exception was only caught by the third middleware, resuming the normal execution of each `After` logic for the second and first middleware. + +
+ ![Middleware handling exceptions](../../media/middlewares_catch_route_exception-light.svg#only-light) + ![Middleware handling exceptions](../../media/middlewares_catch_route_exception-dark.svg#only-dark) + + _Unhandled route exceptions propagate back to the client_ +
+ +=== "Middleware short-circuit by raising exception" + + The third middleware short-circuited the chain by raising an exception and completely skipping the fourth middleware. Because we only caught it in the first middleware, it skipped the `After` logic in the second middleware. + +
+ ![Catching exceptions](../../media/middlewares_catch_exception-light.svg#only-light) + ![Catching exceptions](../../media/middlewares_catch_exception-dark.svg#only-dark) + + _Middleware handling short-circuit exceptions_ +
+ #### Common practices #### Staging area diff --git a/docs/diagram_src/api-middlewares.drawio b/docs/diagram_src/api-middlewares.drawio index 9a3c68901bd..874688f1e44 100644 --- a/docs/diagram_src/api-middlewares.drawio +++ b/docs/diagram_src/api-middlewares.drawio @@ -1,1534 +1,1534 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file From d166de360bcaa3f0d334312bcfecbda0dd046b1c Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Sat, 2 Sep 2023 20:50:01 +0200 Subject: [PATCH 57/85] docs: fix media typo --- docs/core/event_handler/api_gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index e80795294d2..33cc8db63cf 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -461,7 +461,7 @@ Event Handler **calls global middlewares first**, then middlewares defined at th #### Returning early
-![Short-circuiting middleware chain](../../medi/middlewares_early_return-light.svg#only-light) +![Short-circuiting middleware chain](../../media/middlewares_early_return-light.svg#only-light) ![Short-circuiting middleware chain](../../media/middlewares_early_return-dark.svg#only-dark) _Interrupting request flow by returning early_ From f476f7de9bd34700a6090718d72d0db16077f3bd Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Sun, 3 Sep 2023 19:05:14 +0200 Subject: [PATCH 58/85] docs: add being a good citizen section Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 38 ++++++++------------------ 1 file changed, 11 insertions(+), 27 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 33cc8db63cf..7884abd714a 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -537,7 +537,17 @@ While there isn't anything special on how to use [`try/catch`](https://docs.pyth _Middleware handling short-circuit exceptions_
-#### Common practices +#### Being a good citizen + +Middlewares can add subtle improvements to request/response processing, but also add significant complexity if you're not careful. + +Keep the following in mind when authoring middlewares for Event Handler: + +1. **Use built-in features over middlewares**. We include built-in features like [CORS](#cors), [compression](#compress), [binary responses](#binary-responses), [global exception handling](#exception-handling), and [debug mode](#debug-mode) to reduce the need for middlewares. +2. **Call the next middleware**. Return the result of `get_response(app, **kwargs)`, or a [Response object](#fine-grained-responses) when you want to [return early](#returning-early). +3. **Keep a lean scope**. Focus on a single task per middleware to ease composability and maintenance. In [debug mode](#debug-mode), we also print out the order middlewares will be triggered to ease operations. +4. **Catch your own exceptions**. Catch and handle known exceptions to your logic. Unless you want to raise [HTTP Errors](#raising-http-errors), or propagate specific exceptions to the client. To catch all and any exceptions, we recommend you use the [exception_handler](#exception-handling) decorator. +5. **Use context to share data**. Use `app.append_context` to [share contextual data](#sharing-contextual-data) between middlewares and route handlers, and `app.context.get(key)` to fetch them. We clear all contextual data at the end of every request. #### Staging area @@ -565,32 +575,6 @@ While there isn't anything special on how to use [`try/catch`](https://docs.pyth ???+ warning "Ensure your middleware returns the Next Response" Your middleware functions must return the response from calling **get_response** or a modified version of the Response. If you do not return a value your API route will not work and return an API gateway error. -#### More images (light and dark) - -
-![Short-circuiting middleware chain](../../media/middlewares_unhandled_exception-light.svg#only-light) -![Short-circuiting middleware chain](../../media/middlewares_unhandled_exception-dark.svg#only-dark) -_Interrupting request flow by raising an unhandled exception_ -
- -
-![Short-circuiting middleware chain](../../media/middlewares_catch_exception-light.svg#only-light) -![Short-circuiting middleware chain](../../media/middlewares_catch_exception-dark.svg#only-dark) -_Interrupting request flow by raising an exception captured by Middleware_ -
- -
-![Short-circuiting middleware chain](../../media/middlewares_unhandled_route_exception-light.svg#only-light) -![Short-circuiting middleware chain](../../media/middlewares_unhandled_route_exception-dark.svg#only-dark) -_Unhandled exception from route handler_ -
- -
-![Short-circuiting middleware chain](../../media/middlewares_catch_route_exception-light.svg#only-light) -![Short-circuiting middleware chain](../../media/middlewares_catch_route_exception-dark.svg#only-dark) -_Unhandled exception from route handler captured by Middleware_ -
- **This should go under the Router area since we haven't introduced it yet** Middleware functions used in the Router instance will apply to all API routes and will always be processed first in the order they are added to the Router. Route specific middleware added to each route will then be processed in the order they were added in the route definition. From e8a071e7dd0ff575c0250318e84ee9d6790b6a2a Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Sun, 3 Sep 2023 19:16:41 +0200 Subject: [PATCH 59/85] docs: add skeleton for class-based middleware --- docs/core/event_handler/api_gateway.md | 28 ++++---------------------- 1 file changed, 4 insertions(+), 24 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 7884abd714a..1efc7892bd3 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -537,6 +537,10 @@ While there isn't anything special on how to use [`try/catch`](https://docs.pyth _Middleware handling short-circuit exceptions_
+#### Configurable middlewares + +!!! todo "Explain how to create a middleware that accepts configuration with `BaseMiddlewareHandler`" + #### Being a good citizen Middlewares can add subtle improvements to request/response processing, but also add significant complexity if you're not careful. @@ -551,30 +555,6 @@ Keep the following in mind when authoring middlewares for Event Handler: #### Staging area -??? info "How Middleware Works" - Middleware functions are composed in a decorator style where each function controls the request/response flow and can make changes before or after the API handler is called. - - ![Image showing how the middleware flow works](/media/how-middleware-works-1.png) - - 1. Powertools API Route handler executes API Route Handler (wrapped in composed middleware). - 2. Middleware function is called - 3. Before processing code - 4. Calls Next Middleware function (or registered API route handler) - 5. If the next function is middleware, it repeats these steps. The API route code runs and returns if it is the route handler. - 6. After the next middleware (or API handler) returns After processing may be run to post-process the response. - 7. The response is returned by the Middleware function to the caller. - -??? tip "What Middleware is Responsible for" - - They can be chained in a stack, so ensure it does only one thing to maximize re-usability and simplicity. - - Middleware must call the next middleware in the chain or your API handler will never be called. - - Responsible for calling the next middleware function in the stack. - - Can pre-process the Request data, change it or validate it before calling the next middleware function. - - Returning early by throwing an exception or returning a valid response. - - Can process the Response and alter its content depending on the middleware's purpose. - -???+ warning "Ensure your middleware returns the Next Response" - Your middleware functions must return the response from calling **get_response** or a modified version of the Response. If you do not return a value your API route will not work and return an API gateway error. - **This should go under the Router area since we haven't introduced it yet** Middleware functions used in the Router instance will apply to all API routes and will always be processed first in the order they are added to the Router. Route specific middleware added to each route will then be processed in the order they were added in the route definition. From 1c0977a72de85134122af02fcda2ce689cce5c8f Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 4 Sep 2023 11:57:00 +0200 Subject: [PATCH 60/85] chore: test class based middlewares --- .../event_handler/middlewares/base.py | 5 +-- tests/events/apiGatewayProxyEvent.json | 2 +- .../event_handler/test_api_middlewares.py | 36 ++++++++++++++++++- 3 files changed, 39 insertions(+), 4 deletions(-) diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index 7b910a31651..2171c1c2e40 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -2,6 +2,7 @@ from typing import Any, Callable from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response +from aws_lambda_powertools.event_handler.types import NextMiddlewareCallback class BaseMiddlewareHandler(ABC): @@ -67,7 +68,7 @@ class BaseMiddlewareHandler(ABC): """ @abstractmethod - def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **kwargs) -> Response: + def handler(self, app: ApiGatewayResolver, get_response: NextMiddlewareCallback, **kwargs) -> Response: """ The Middleware Handler @@ -75,7 +76,7 @@ def handler(self, app: ApiGatewayResolver, get_response: Callable[..., Any], **k ---------- app: ApiGatewayResolver The ApiGatewayResolver object - get_response: Callable[..., Any] + get_response: NextMiddlewareCallback The next middleware handler in the chain kwargs: Any Any additional arguments to pass to the next middleware handler diff --git a/tests/events/apiGatewayProxyEvent.json b/tests/events/apiGatewayProxyEvent.json index da814c91100..3f095e28e45 100644 --- a/tests/events/apiGatewayProxyEvent.json +++ b/tests/events/apiGatewayProxyEvent.json @@ -78,4 +78,4 @@ "stageVariables": null, "body": "Hello from Lambda!", "isBase64Encoded": false -} +} \ No newline at end of file diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index 8a79b2953b6..21395680467 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -5,12 +5,13 @@ APIGatewayHttpResolver, ApiGatewayResolver, APIGatewayRestResolver, + NextMiddlewareCallback, ProxyEventType, Response, Router, ) from aws_lambda_powertools.event_handler.exceptions import BadRequestError -from aws_lambda_powertools.event_handler.middlewares import SchemaValidationMiddleware +from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler, SchemaValidationMiddleware from tests.functional.utils import load_event API_REST_EVENT = load_event("apiGatewayProxyEvent.json") @@ -375,3 +376,36 @@ def get_api_route(app_injected: str, router_injected: str, injected: str): # THEN process event correctly assert result["statusCode"] == 200 assert result["body"] == to_inject + + +def test_class_based_middleware(): + # GIVEN a class-based middleware implementing BaseMiddlewareHandler correctly + class CorrelationIdMiddleware(BaseMiddlewareHandler): + def __init__(self, header: str): + super().__init__() + self.header = header + + def handler(self, app: ApiGatewayResolver, get_response: NextMiddlewareCallback, **kwargs) -> Response: + request_id = app.current_event.request_context.request_id # type: ignore[attr-defined] # using REST event in a base Resolver # noqa: E501 + correlation_id = app.current_event.get_header_value( + name=self.header, + default_value=request_id, + ) # noqa: E501 + + response = get_response(app, **kwargs) + response.headers[self.header] = correlation_id + + return response + + resolver = ApiGatewayResolver() + event = load_event("apiGatewayProxyEvent.json") + + # WHEN instantiated with extra configuration as part of a route handler + @resolver.get("/my/path", middlewares=[CorrelationIdMiddleware(header="X-Correlation-Id")]) + def post_lambda(): + return {"hello": "world"} + + # THEN it should work as any other middleware when a request is processed + result = resolver(event, {}) + assert result["statusCode"] == 200 + assert result["multiValueHeaders"]["X-Correlation-Id"][0] == resolver.current_event.request_context.request_id # type: ignore[attr-defined] # noqa: E501 From 7d361b6268c0a500efeea9e07572ca26f587e142 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 4 Sep 2023 11:57:39 +0200 Subject: [PATCH 61/85] docs: rename class based section --- docs/core/event_handler/api_gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 1efc7892bd3..056c2282e73 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -537,7 +537,7 @@ While there isn't anything special on how to use [`try/catch`](https://docs.pyth _Middleware handling short-circuit exceptions_ -#### Configurable middlewares +#### Extending middlewares !!! todo "Explain how to create a middleware that accepts configuration with `BaseMiddlewareHandler`" From 85e65b04a78c9fc35868ba339c0d27caadc626ed Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Mon, 4 Sep 2023 20:29:12 +1000 Subject: [PATCH 62/85] feat(middlewares): remove kwargs from middleware signature for cleaner DX and relabler get_response to next_middleware for consistency --- .../event_handler/api_gateway.py | 50 ++++--- .../event_handler/middlewares/base.py | 26 ++-- .../middlewares/schema_validation.py | 7 +- .../src/custom_middlewares.py | 8 +- .../src/middleware_getting_started.py | 4 +- .../middleware_global_middlewares_module.py | 12 +- .../event_handler/test_api_gateway.py | 3 +- .../event_handler/test_api_middlewares.py | 129 ++++++++++-------- 8 files changed, 127 insertions(+), 112 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 9c90c17f0cd..4d6a749eb15 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/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,7 +719,7 @@ 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. @@ -726,8 +727,6 @@ def __call__(self, app: BaseRouter, **kwargs) -> Union[Dict, Tuple, Response]: ---------- 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,10 +761,8 @@ 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 ------- @@ -773,9 +770,10 @@ def _registered_api_adapter( 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)""" ... diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index 2171c1c2e40..9f6fbe90a27 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/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,7 +91,7 @@ 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. @@ -101,14 +99,12 @@ def __call__(self, app: ApiGatewayResolver, get_response: Callable[..., Any], ** ---------- 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) diff --git a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py index be40520f53b..be231f25c14 100644 --- a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py +++ b/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: diff --git a/examples/event_handler_rest/src/custom_middlewares.py b/examples/event_handler_rest/src/custom_middlewares.py index 7fdcb83a1d0..a369210855f 100644 --- a/examples/event_handler_rest/src/custom_middlewares.py +++ b/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) diff --git a/examples/event_handler_rest/src/middleware_getting_started.py b/examples/event_handler_rest/src/middleware_getting_started.py index b8a8014ce4e..c8417cad111 100644 --- a/examples/event_handler_rest/src/middleware_getting_started.py +++ b/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)! diff --git a/examples/event_handler_rest/src/middleware_global_middlewares_module.py b/examples/event_handler_rest/src/middleware_global_middlewares_module.py index 3f1d9e12b2f..7ec7ccb2bf7 100644 --- a/examples/event_handler_rest/src/middleware_global_middlewares_module.py +++ b/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) diff --git a/tests/functional/event_handler/test_api_gateway.py b/tests/functional/event_handler/test_api_gateway.py index 44781193b39..b5f196200a9 100644 --- a/tests/functional/event_handler/test_api_gateway.py +++ b/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(): diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index 21395680467..1eaadad5ec1 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -5,6 +5,7 @@ APIGatewayHttpResolver, ApiGatewayResolver, APIGatewayRestResolver, + BaseRouter, NextMiddlewareCallback, ProxyEventType, Response, @@ -26,25 +27,30 @@ (APIGatewayHttpResolver(), API_RESTV2_EVENT), ], ) -def test_route_with_middleware(app, event): +def test_route_with_middleware(app: BaseRouter, event): # define custom middleware to inject new argument - "custom" - def middleware_1(app, get_response, **kwargs): - # inject a variable into the kwargs - response = get_response(app, custom="custom", **kwargs) + def middleware_1(app: BaseRouter, next_middleware: NextMiddlewareCallback): + # add additional data to Router Context + app.append_context(custom="custom") + response = next_middleware(app) return response # define custom middleware to inject new argument - "another_one" - def middleware_2(app, get_response, **kwargs): - # inject a variable into the kwargs - response = get_response(app, another_one=6, **kwargs) + def middleware_2(app: BaseRouter, next_middleware: NextMiddlewareCallback): + # add additional data to Router Context + app.append_context(another_one=6) + response = next_middleware(app) return response @app.get("/my/path", middlewares=[middleware_1, middleware_2]) - def get_lambda(another_one: int, custom: str) -> Response: + def get_lambda() -> Response: + another_one = app.context.get("another_one") + custom = app.context.get("custom") assert another_one == 6 assert custom == "custom" + return Response(200, content_types.TEXT_HTML, "foo") # WHEN calling the event handler @@ -76,27 +82,32 @@ def get_lambda(another_one: int, custom: str) -> Response: ), ], ) -def test_with_router_middleware(app, event, other_event): +def test_with_router_middleware(app: BaseRouter, event, other_event): # define custom middleware to inject new argument - "custom" - def global_middleware(app, get_response, **kwargs): - # inject a variable into the kwargs - response = get_response(app, custom="custom", **kwargs) + def global_middleware(app: BaseRouter, next_middleware: NextMiddlewareCallback): + # add custom data to context + app.append_context(custom="custom") + response = next_middleware(app) return response # define custom middleware to inject new argument - "another_one" - def middleware_2(app, get_response, **kwargs): - # inject a variable into the kwargs - response = get_response(app, another_one=6, **kwargs) + def middleware_2(app: BaseRouter, next_middleware: NextMiddlewareCallback): + # add data to resolver context + app.append_context(another_one=6) + response = next_middleware(app) return response app.use([global_middleware]) @app.get("/my/path", middlewares=[middleware_2]) - def get_lambda(another_one: int, custom: str) -> Response: + def get_lambda() -> Response: + another_one: int = app.context.get("another_one") + custom: str = app.context.get("custom") assert another_one == 6 assert custom == "custom" + return Response(200, content_types.TEXT_HTML, "foo") # WHEN calling the event handler @@ -108,8 +119,10 @@ def get_lambda(another_one: int, custom: str) -> Response: assert result["body"] == "foo" @app.get("/other/path") - def get_other_lambda(custom: str) -> Response: + def get_other_lambda() -> Response: + custom: str = app.context.get("custom") assert custom == "custom" + return Response(200, content_types.TEXT_HTML, "other_foo") # WHEN calling the event handler @@ -129,15 +142,17 @@ def get_other_lambda(custom: str) -> Response: (APIGatewayHttpResolver(), API_RESTV2_EVENT), ], ) -def test_dynamic_route_with_middleware(app, event): - def middleware_one(app, get_response, **kwargs): - # inject a variable into the kwargs - response = get_response(app, injected="injected_value", **kwargs) +def test_dynamic_route_with_middleware(app: BaseRouter, event): + def middleware_one(app: BaseRouter, next_middleware: NextMiddlewareCallback): + # inject data into the resolver context + app.append_context(injected="injected_value") + response = next_middleware(app) return response @app.get("//", middlewares=[middleware_one]) - def get_lambda(my_id: str, name: str, injected: str) -> Response: + def get_lambda(my_id: str, name: str) -> Response: + injected: str = app.context.get("injected") assert name == "my" assert injected == "injected_value" @@ -159,26 +174,27 @@ def get_lambda(my_id: str, name: str, injected: str) -> Response: (APIGatewayHttpResolver(), API_RESTV2_EVENT), ], ) -def test_middleware_early_return(app, event): - def middleware_one(app, get_response, **context): - # inject a variable into the kwargs - response = get_response(app, injected="injected_value", **context) +def test_middleware_early_return(app: BaseRouter, event): + def middleware_one(app: BaseRouter, next_middleware): + # inject a variable into resolver context + app.append_context(injected="injected_value") + response = next_middleware(app) return response - def early_return_middleware(app, get_response, **context): - assert context.get("injected") == "injected_value" + def early_return_middleware(app: BaseRouter, next_middleware: NextMiddlewareCallback): + assert app.context.get("injected") == "injected_value" return Response(400, content_types.TEXT_HTML, "bad_response") - def not_executed_middleware(app, get_response, **context): + def not_executed_middleware(app: BaseRouter, next_middleware: NextMiddlewareCallback): # This should never be executed - if it is an excpetion will be raised raise NotImplementedError() @app.get("//", middlewares=[middleware_one, early_return_middleware, not_executed_middleware]) - def get_lambda(my_id: str, name: str, injected: str) -> Response: + def get_lambda(my_id: str, name: str) -> Response: assert name == "my" - assert injected == "injected_value" + assert app.context.get("injected") == "injected_value" return Response(200, content_types.TEXT_HTML, my_id) @@ -207,7 +223,7 @@ def get_lambda(my_id: str, name: str, injected: str) -> Response: ), ], ) -def test_pass_schema_validation(app, event, validation_schema): +def test_pass_schema_validation(app: BaseRouter, event, validation_schema): @app.post("/my/path", middlewares=[SchemaValidationMiddleware(validation_schema)]) def post_lambda() -> Response: return Response(200, content_types.TEXT_HTML, "path") @@ -237,7 +253,7 @@ def post_lambda() -> Response: ), ], ) -def test_fail_schema_validation(app, event, validation_schema): +def test_fail_schema_validation(app: BaseRouter, event, validation_schema): @app.post("/my/path", middlewares=[SchemaValidationMiddleware(validation_schema)]) def post_lambda() -> Response: return Response(200, content_types.TEXT_HTML, "Should not be returned") @@ -271,7 +287,7 @@ def post_lambda() -> Response: ), ], ) -def test_invalid_schema_validation(app, event): +def test_invalid_schema_validation(app: BaseRouter, event): @app.post("/my/path", middlewares=[SchemaValidationMiddleware(inbound_schema="schema.json")]) def post_lambda() -> Response: return Response(200, content_types.TEXT_HTML, "Should not be returned") @@ -293,26 +309,27 @@ def post_lambda() -> Response: (APIGatewayHttpResolver(), API_RESTV2_EVENT), ], ) -def test_middleware_short_circuit_via_httperrors(app, event): - def middleware_one(app, get_response, **context): +def test_middleware_short_circuit_via_httperrors(app: BaseRouter, event): + def middleware_one(app: BaseRouter, next_middleware: NextMiddlewareCallback): # inject a variable into the kwargs of the middleware chain - response = get_response(app, injected="injected_value", **context) + app.append_context(injected="injected_value") + response = next_middleware(app) return response - def early_return_middleware(app, get_response, **context): + def early_return_middleware(app: BaseRouter, next_middleware: NextMiddlewareCallback): # ensure "injected" context variable is passed in by middleware_one - assert context.get("injected") == "injected_value" + assert app.context.get("injected") == "injected_value" raise BadRequestError("bad_response") - def not_executed_middleware(app, get_response, **context): + def not_executed_middleware(app: BaseRouter, next_middleware: NextMiddlewareCallback): # This should never be executed - if it is an excpetion will be raised raise NotImplementedError() @app.get("//", middlewares=[middleware_one, early_return_middleware, not_executed_middleware]) - def get_lambda(my_id: str, name: str, injected: str) -> Response: + def get_lambda(my_id: str, name: str) -> Response: assert name == "my" - assert injected == "injected_value" + assert app.context.get("injected") == "injected_value" return Response(200, content_types.TEXT_HTML, my_id) @@ -332,21 +349,23 @@ def get_lambda(my_id: str, name: str, injected: str) -> Response: (APIGatewayHttpResolver(), API_RESTV2_EVENT), ], ) -def test_api_gateway_app_router_with_middlewares(app, event): +def test_api_gateway_app_router_with_middlewares(app: BaseRouter, event): # GIVEN a Router with registered routes router = Router() - def app_middleware(app, get_response, **context): - # inject a variable into the kwargs of the middleware chain - response = get_response(app, app_injected="app_value", **context) + def app_middleware(app: BaseRouter, next_middleware): + # inject a variable into the resolver context + app.append_context(app_injected="app_value") + response = next_middleware(app) return response app.use(middlewares=[app_middleware]) - def router_middleware(app, get_response, **context): - # inject a variable into the kwargs of the middleware chain - response = get_response(app, router_injected="router_value", **context) + def router_middleware(app: BaseRouter, next_middleware): + # inject a variable into the resolver context + app.append_context(router_injected="router_value") + response = next_middleware(app) return response @@ -354,18 +373,20 @@ def router_middleware(app, get_response, **context): to_inject: str = "injected_value" - def middleware_one(app, get_response, **context): + def middleware_one(app: BaseRouter, next_middleware: NextMiddlewareCallback): # inject a variable into the kwargs of the middleware chain - response = get_response(app, injected=to_inject, **context) + app.append_context(injected=to_inject) + response = next_middleware(app) return response @router.get("/my/path", middlewares=[middleware_one]) - def get_api_route(app_injected: str, router_injected: str, injected: str): + def get_api_route(): # make sure value is injected by middleware_one + injected: str = app.context.get("injected") assert injected == to_inject - assert router_injected == "router_value" - assert app_injected == "app_value" + assert app.context.get("router_injected") == "router_value" + assert app.context.get("app_injected") == "app_value" return Response(200, content_types.TEXT_HTML, injected) From 3a2031846d47cf7682f04a5db90337c50a44124a Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Mon, 4 Sep 2023 21:03:27 +1000 Subject: [PATCH 63/85] feat(middlewares): align signatures for middlewareprocessing --- .../event_handler/api_gateway.py | 48 ++++++++++--------- .../event_handler/middlewares/base.py | 5 +- .../middlewares/schema_validation.py | 6 +-- .../middleware_global_middlewares_module.py | 4 +- 4 files changed, 33 insertions(+), 30 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 4d6a749eb15..aa31a63d2a7 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -49,6 +49,16 @@ _ROUTE_REGEX = "^{}$" +class NextMiddlewareCallback(Protocol): + def __call__(self, app: "ApiGatewayResolver") -> "Response": + """Protocol for callback regardless of next_middleware(app), next(app)""" + ... + + def __name__(self) -> str: # noqa A003 + """Protocol for name of the Middleware""" + ... + + class ProxyEventType(Enum): """An enumerations of the supported proxy event types.""" @@ -219,7 +229,7 @@ def __init__( cors: bool, compress: bool, cache_control: Optional[str], - middlewares: Optional[List[Callable[..., Any]]], + middlewares: Optional[List[NextMiddlewareCallback]], ): """ @@ -238,7 +248,7 @@ def __init__( Whether or not to enable gzip compression for this route cache_control: Optional[str] The cache control header value, example "max-age=3600" - middlewares: Optional[List[Callable[..., Any]]] + middlewares: Optional[List[NextMiddlewareCallback]] The list of route middlewares. These are called in the order they are provided. """ @@ -453,7 +463,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable[..., Any]]] = None, + middlewares: Optional[List[NextMiddlewareCallback]] = None, ): raise NotImplementedError() @@ -493,7 +503,7 @@ def get( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable[..., Any]]] = None, + middlewares: Optional[List[NextMiddlewareCallback]] = None, ): """Get route decorator with GET `method` @@ -525,7 +535,7 @@ def post( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable[..., Any]]] = None, + middlewares: Optional[List[NextMiddlewareCallback]] = None, ): """Post route decorator with POST `method` @@ -558,7 +568,7 @@ def put( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable[..., Any]]] = None, + middlewares: Optional[List[NextMiddlewareCallback]] = None, ): """Put route decorator with PUT `method` @@ -591,7 +601,7 @@ def delete( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable[..., Any]]] = None, + middlewares: Optional[List[NextMiddlewareCallback]] = None, ): """Delete route decorator with DELETE `method` @@ -698,11 +708,11 @@ class MiddlewareFrame: def __init__( self, - current_middleware: Callable[..., Any], - next_middleware: Callable[..., Any], + current_middleware: NextMiddlewareCallback, + next_middleware: NextMiddlewareCallback, ) -> None: - self.current_middleware: Callable[..., Any] = current_middleware - self.next_middleware: Callable[..., Any] = next_middleware + self.current_middleware: NextMiddlewareCallback = current_middleware + self.next_middleware: NextMiddlewareCallback = next_middleware self._next_middleware_name = next_middleware.__name__ @property @@ -746,7 +756,7 @@ def __call__(self, app: BaseRouter) -> Union[Dict, Tuple, Response]: def _registered_api_adapter( app: "ApiGatewayResolver", - next_middleware: Callable[..., Any], + next_middleware: NextMiddlewareCallback, ) -> Union[Dict, Tuple, Response]: """ Calls the registered API using the "_route_args" from the Resolver context to ensure the last call @@ -761,7 +771,7 @@ def _registered_api_adapter( ---------- app: ApiGatewayResolver The API Gateway resolver - next_middleware: Callable[..., Any] + next_middleware: NextMiddlewareCallback The function to handle the API Returns @@ -852,7 +862,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable[..., Any]]] = None, + middlewares: Optional[List[NextMiddlewareCallback]] = None, ): """Route decorator includes parameter `method`""" @@ -1242,7 +1252,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable[..., Any]]] = None, + middlewares: Optional[List[NextMiddlewareCallback]] = None, ): def register_route(func: Callable): # Convert methods to tuple. It needs to be hashable as its part of the self._routes dict key @@ -1288,7 +1298,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[Callable[..., Any]]] = None, + middlewares: Optional[List[NextMiddlewareCallback]] = None, ): # NOTE: see #1552 for more context. return super().route(rule.rstrip("/"), method, cors, compress, cache_control, middlewares) @@ -1325,9 +1335,3 @@ def __init__( ): """Amazon Application Load Balancer (ALB) resolver""" super().__init__(ProxyEventType.ALBEvent, cors, debug, serializer, strip_prefixes) - - -class NextMiddlewareCallback(Protocol): - def __call__(self, app: ApiGatewayResolver) -> Response: - """Protocol for callback regardless of next_middleware(app), next(app)""" - ... diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index 9f6fbe90a27..f56010ca82c 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -1,5 +1,4 @@ from abc import ABC, abstractmethod -from typing import Any, Callable from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response from aws_lambda_powertools.event_handler.types import NextMiddlewareCallback @@ -68,7 +67,7 @@ class BaseMiddlewareHandler(ABC): """ @abstractmethod - def handler(self, app: ApiGatewayResolver, get_response: NextMiddlewareCallback) -> Response: + def handler(self, app: ApiGatewayResolver, next_middleware: NextMiddlewareCallback) -> Response: """ The Middleware Handler @@ -76,7 +75,7 @@ def handler(self, app: ApiGatewayResolver, get_response: NextMiddlewareCallback) ---------- app: ApiGatewayResolver The ApiGatewayResolver object - get_response: NextMiddlewareCallback + next_middleware: NextMiddlewareCallback The next middleware handler in the chain Returns diff --git a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py index be231f25c14..ded46c72478 100644 --- a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py +++ b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py @@ -1,7 +1,7 @@ import logging -from typing import Any, Callable, Dict, Optional +from typing import Dict, Optional -from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response +from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, NextMiddlewareCallback, Response from aws_lambda_powertools.event_handler.exceptions import BadRequestError, InternalServerError from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler from aws_lambda_powertools.utilities.validation import validate @@ -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, next_middleware: Callable[..., Any]) -> Response: + def handler(self, app: ApiGatewayResolver, next_middleware: NextMiddlewareCallback) -> Response: """ Validate using Powertools validate() utility. diff --git a/examples/event_handler_rest/src/middleware_global_middlewares_module.py b/examples/event_handler_rest/src/middleware_global_middlewares_module.py index 7ec7ccb2bf7..b3638a2bfea 100644 --- a/examples/event_handler_rest/src/middleware_global_middlewares_module.py +++ b/examples/event_handler_rest/src/middleware_global_middlewares_module.py @@ -5,7 +5,7 @@ logger = Logger() -def log_request_response(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback, **kwargs) -> Response: +def log_request_response(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback) -> Response: logger.info("Incoming request", path=app.current_event.path, request=app.current_event.raw_event) result = next_middleware(app) @@ -14,7 +14,7 @@ def log_request_response(app: APIGatewayRestResolver, next_middleware: NextMiddl return result -def inject_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback, **kwargs) -> Response: +def inject_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback) -> 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 From 5edde6aa01d286374a39298f63ea0040105514bf Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Mon, 4 Sep 2023 21:35:49 +1000 Subject: [PATCH 64/85] feat(middlewares): cleanup typing for next callbacks --- .../event_handler/api_gateway.py | 38 +++++++++---------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index aa31a63d2a7..f8b67e2c83c 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -229,7 +229,7 @@ def __init__( cors: bool, compress: bool, cache_control: Optional[str], - middlewares: Optional[List[NextMiddlewareCallback]], + middlewares: Optional[List[Callable[..., Any]]], ): """ @@ -248,7 +248,7 @@ def __init__( Whether or not to enable gzip compression for this route cache_control: Optional[str] The cache control header value, example "max-age=3600" - middlewares: Optional[List[NextMiddlewareCallback]] + middlewares: Optional[List[Callable[..., Any]]] The list of route middlewares. These are called in the order they are provided. """ @@ -316,7 +316,7 @@ def __call__( # 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: + def _build_middleware_stack(self, router_middlewares: List[Callable[..., Any]]) -> None: """ Builds the middleware stack for the handler by wrapping each handler in an instance of MiddlewareWrapper which is used to contain the state @@ -463,7 +463,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[NextMiddlewareCallback]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): raise NotImplementedError() @@ -503,7 +503,7 @@ def get( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[NextMiddlewareCallback]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): """Get route decorator with GET `method` @@ -535,7 +535,7 @@ def post( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[NextMiddlewareCallback]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): """Post route decorator with POST `method` @@ -568,7 +568,7 @@ def put( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[NextMiddlewareCallback]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): """Put route decorator with PUT `method` @@ -601,7 +601,7 @@ def delete( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[NextMiddlewareCallback]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): """Delete route decorator with DELETE `method` @@ -708,15 +708,15 @@ class MiddlewareFrame: def __init__( self, - current_middleware: NextMiddlewareCallback, - next_middleware: NextMiddlewareCallback, + current_middleware: Callable[..., Any], + next_middleware: Callable[..., Any], ) -> None: - self.current_middleware: NextMiddlewareCallback = current_middleware - self.next_middleware: NextMiddlewareCallback = next_middleware + self.current_middleware: Callable[..., Any] = current_middleware + self.next_middleware: Callable[..., Any] = next_middleware self._next_middleware_name = next_middleware.__name__ @property - def __name__(self): # noqa: A003 + def __name__(self) -> str: # noqa: A003 """Current middleware name It ensures backward compatibility with view functions being callable. This @@ -729,7 +729,7 @@ 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) -> Union[Dict, Tuple, Response]: + def __call__(self, app: "ApiGatewayResolver") -> Union[Dict, Tuple, Response]: """ Call the middleware Frame to process the request. @@ -756,7 +756,7 @@ def __call__(self, app: BaseRouter) -> Union[Dict, Tuple, Response]: def _registered_api_adapter( app: "ApiGatewayResolver", - next_middleware: NextMiddlewareCallback, + next_middleware: Callable[..., Any], ) -> Union[Dict, Tuple, Response]: """ Calls the registered API using the "_route_args" from the Resolver context to ensure the last call @@ -771,7 +771,7 @@ def _registered_api_adapter( ---------- app: ApiGatewayResolver The API Gateway resolver - next_middleware: NextMiddlewareCallback + next_middleware: Callable[..., Any] The function to handle the API Returns @@ -862,7 +862,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[NextMiddlewareCallback]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): """Route decorator includes parameter `method`""" @@ -1252,7 +1252,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[NextMiddlewareCallback]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): def register_route(func: Callable): # Convert methods to tuple. It needs to be hashable as its part of the self._routes dict key @@ -1298,7 +1298,7 @@ def route( cors: Optional[bool] = None, compress: bool = False, cache_control: Optional[str] = None, - middlewares: Optional[List[NextMiddlewareCallback]] = None, + middlewares: Optional[List[Callable[..., Any]]] = None, ): # NOTE: see #1552 for more context. return super().route(rule.rstrip("/"), method, cors, compress, cache_control, middlewares) From a0e784bfdfb1be69637a2ba95124b84b39a3376c Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Mon, 4 Sep 2023 21:55:54 +1000 Subject: [PATCH 65/85] feat(middlewares): align typing for next_middlewares for consistency --- .../event_handler/api_gateway.py | 20 +++++++++---------- .../event_handler/middlewares/base.py | 10 +++++----- .../middlewares/schema_validation.py | 6 +++--- 3 files changed, 18 insertions(+), 18 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index f8b67e2c83c..4354c74fb00 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -49,16 +49,6 @@ _ROUTE_REGEX = "^{}$" -class NextMiddlewareCallback(Protocol): - def __call__(self, app: "ApiGatewayResolver") -> "Response": - """Protocol for callback regardless of next_middleware(app), next(app)""" - ... - - def __name__(self) -> str: # noqa A003 - """Protocol for name of the Middleware""" - ... - - class ProxyEventType(Enum): """An enumerations of the supported proxy event types.""" @@ -1335,3 +1325,13 @@ def __init__( ): """Amazon Application Load Balancer (ALB) resolver""" super().__init__(ProxyEventType.ALBEvent, cors, debug, serializer, strip_prefixes) + + +class NextMiddlewareCallback(Protocol): + def __call__(self, app: ApiGatewayResolver) -> Response: + """Protocol for callback regardless of next_middleware(app), next(app)""" + ... + + def __name__(self) -> str: # noqa A003 + """Protocol for name of the Middleware""" + ... diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index f56010ca82c..3725a965024 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -1,7 +1,7 @@ from abc import ABC, abstractmethod +from typing import Any, Callable from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response -from aws_lambda_powertools.event_handler.types import NextMiddlewareCallback class BaseMiddlewareHandler(ABC): @@ -67,7 +67,7 @@ class BaseMiddlewareHandler(ABC): """ @abstractmethod - def handler(self, app: ApiGatewayResolver, next_middleware: NextMiddlewareCallback) -> Response: + def handler(self, app: ApiGatewayResolver, next_middleware: Callable[..., Any]) -> Response: """ The Middleware Handler @@ -75,7 +75,7 @@ def handler(self, app: ApiGatewayResolver, next_middleware: NextMiddlewareCallba ---------- app: ApiGatewayResolver The ApiGatewayResolver object - next_middleware: NextMiddlewareCallback + next_middleware: Callable[..., Any] The next middleware handler in the chain Returns @@ -90,7 +90,7 @@ def handler(self, app: ApiGatewayResolver, next_middleware: NextMiddlewareCallba def __name__(self) -> str: # noqa A003 return str(self.__class__.__name__) - def __call__(self, app: ApiGatewayResolver, next_middleware: NextMiddlewareCallback) -> Response: + def __call__(self, app: ApiGatewayResolver, next_middleware: Callable[..., Any]) -> Response: """ The Middleware handler function. @@ -98,7 +98,7 @@ def __call__(self, app: ApiGatewayResolver, next_middleware: NextMiddlewareCallb ---------- app: ApiGatewayResolver The ApiGatewayResolver object - next_middleware: NextMiddlewareCallback + next_middleware: Callable[..., Any] The next middleware handler in the chain Returns diff --git a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py index ded46c72478..be231f25c14 100644 --- a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py +++ b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py @@ -1,7 +1,7 @@ import logging -from typing import Dict, Optional +from typing import Any, Callable, Dict, Optional -from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, NextMiddlewareCallback, Response +from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response from aws_lambda_powertools.event_handler.exceptions import BadRequestError, InternalServerError from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler from aws_lambda_powertools.utilities.validation import validate @@ -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, next_middleware: NextMiddlewareCallback) -> Response: + def handler(self, app: ApiGatewayResolver, next_middleware: Callable[..., Any]) -> Response: """ Validate using Powertools validate() utility. From d8cf386ea52e25610c9f8b2b57e38f47946e8f73 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 4 Sep 2023 17:09:57 +0200 Subject: [PATCH 66/85] chore: use generics to accept any event handler Signed-off-by: heitorlessa --- .../event_handler/middlewares/base.py | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index 3725a965024..d04c06edba9 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -1,10 +1,12 @@ from abc import ABC, abstractmethod -from typing import Any, Callable +from typing import Any, Callable, Generic, TypeVar from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response +EventHandlerResolver = TypeVar("EventHandlerResolver", bound=ApiGatewayResolver) -class BaseMiddlewareHandler(ABC): + +class BaseMiddlewareHandler(Generic[EventHandlerResolver], ABC): """ Base class for Middleware Handlers @@ -67,14 +69,14 @@ class BaseMiddlewareHandler(ABC): """ @abstractmethod - def handler(self, app: ApiGatewayResolver, next_middleware: Callable[..., Any]) -> Response: + def handler(self, app: EventHandlerResolver, next_middleware: Callable[..., Any]) -> Response: """ The Middleware Handler Parameters ---------- - app: ApiGatewayResolver - The ApiGatewayResolver object + app: EventHandlerResolver + An instance of an Event Handler that implements ApiGatewayResolver next_middleware: Callable[..., Any] The next middleware handler in the chain @@ -90,14 +92,14 @@ def handler(self, app: ApiGatewayResolver, next_middleware: Callable[..., Any]) def __name__(self) -> str: # noqa A003 return str(self.__class__.__name__) - def __call__(self, app: ApiGatewayResolver, next_middleware: Callable[..., Any]) -> Response: + def __call__(self, app: EventHandlerResolver, next_middleware: Callable[..., Any]) -> Response: """ The Middleware handler function. Parameters ---------- app: ApiGatewayResolver - The ApiGatewayResolver object + An instance of an Event Handler that implements ApiGatewayResolver next_middleware: Callable[..., Any] The next middleware handler in the chain From f5a613a996315d29f1aa4b48008999d3778cd7f6 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 4 Sep 2023 17:31:03 +0200 Subject: [PATCH 67/85] refactor: tech debt overload on get_header_value for middleware example work properly --- .../event_handler/api_gateway.py | 6 +++++- .../utilities/data_classes/common.py | 21 +++++++++++++++++-- .../utilities/data_classes/vpc_lattice.py | 20 +++++++++++++++++- .../src/split_route_module.py | 6 +++++- .../src/split_route_prefix_module.py | 6 +++++- 5 files changed, 53 insertions(+), 6 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 4354c74fb00..a60bd0a9b4a 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -388,7 +388,11 @@ def _has_compression_enabled( bool True if compression is enabled and the "gzip" encoding is accepted, False otherwise. """ - encoding: str = event.get_header_value(name="accept-encoding", default_value="", case_sensitive=False) # type: ignore[assignment] # noqa: E501 + encoding: str = event.get_header_value( + name="accept-encoding", + default_value="", + case_sensitive=False, + ) # noqa: E501 if "gzip" in encoding: if response_compression is not None: return response_compression # e.g., Response(compress=False/True)) diff --git a/aws_lambda_powertools/utilities/data_classes/common.py b/aws_lambda_powertools/utilities/data_classes/common.py index 7a3fc8ab404..fa7c5296042 100644 --- a/aws_lambda_powertools/utilities/data_classes/common.py +++ b/aws_lambda_powertools/utilities/data_classes/common.py @@ -1,7 +1,7 @@ import base64 import json from collections.abc import Mapping -from typing import Any, Callable, Dict, Iterator, List, Optional +from typing import Any, Callable, Dict, Iterator, List, Optional, overload from aws_lambda_powertools.shared.headers_serializer import BaseHeadersSerializer from aws_lambda_powertools.utilities.data_classes.shared_functions import ( @@ -156,7 +156,24 @@ def get_query_string_value(self, name: str, default_value: Optional[str] = None) default_value=default_value, ) - # Maintenance: missing @overload to ensure return type is a str when default_value is set + @overload + def get_header_value( + self, + name: str, + default_value: str, + case_sensitive: Optional[bool] = False, + ) -> str: + ... + + @overload + def get_header_value( + self, + name: str, + default_value: Optional[str] = None, + case_sensitive: Optional[bool] = False, + ) -> Optional[str]: + ... + def get_header_value( self, name: str, diff --git a/aws_lambda_powertools/utilities/data_classes/vpc_lattice.py b/aws_lambda_powertools/utilities/data_classes/vpc_lattice.py index ffa9cb263ab..35194f1f3f0 100644 --- a/aws_lambda_powertools/utilities/data_classes/vpc_lattice.py +++ b/aws_lambda_powertools/utilities/data_classes/vpc_lattice.py @@ -1,4 +1,4 @@ -from typing import Any, Dict, Optional +from typing import Any, Dict, Optional, overload from aws_lambda_powertools.shared.headers_serializer import ( BaseHeadersSerializer, @@ -91,6 +91,24 @@ def get_query_string_value(self, name: str, default_value: Optional[str] = None) default_value=default_value, ) + @overload + def get_header_value( + self, + name: str, + default_value: str, + case_sensitive: Optional[bool] = False, + ) -> str: + ... + + @overload + def get_header_value( + self, + name: str, + default_value: Optional[str] = None, + case_sensitive: Optional[bool] = False, + ) -> Optional[str]: + ... + def get_header_value( self, name: str, diff --git a/examples/event_handler_rest/src/split_route_module.py b/examples/event_handler_rest/src/split_route_module.py index 0462623f90b..b6a91b3fb3b 100644 --- a/examples/event_handler_rest/src/split_route_module.py +++ b/examples/event_handler_rest/src/split_route_module.py @@ -25,7 +25,11 @@ def get_todos(): @router.get("/todos/") @tracer.capture_method def get_todo_by_id(todo_id: str): # value come as str - api_key: str = router.current_event.get_header_value(name="X-Api-Key", case_sensitive=True, default_value="") # type: ignore[assignment] # sentinel typing # noqa: E501 + api_key: str = router.current_event.get_header_value( + name="X-Api-Key", + case_sensitive=True, + default_value="", + ) # noqa: E501 todos: Response = requests.get(f"{endpoint}/{todo_id}", headers={"X-Api-Key": api_key}) todos.raise_for_status() diff --git a/examples/event_handler_rest/src/split_route_prefix_module.py b/examples/event_handler_rest/src/split_route_prefix_module.py index 41fcf8eed31..aa17e0cd347 100644 --- a/examples/event_handler_rest/src/split_route_prefix_module.py +++ b/examples/event_handler_rest/src/split_route_prefix_module.py @@ -25,7 +25,11 @@ def get_todos(): @router.get("/") @tracer.capture_method def get_todo_by_id(todo_id: str): # value come as str - api_key: str = router.current_event.get_header_value(name="X-Api-Key", case_sensitive=True, default_value="") # type: ignore[assignment] # sentinel typing # noqa: E501 + api_key: str = router.current_event.get_header_value( + name="X-Api-Key", + case_sensitive=True, + default_value="", + ) # sentinel typing # noqa: E501 todos: Response = requests.get(f"{endpoint}/{todo_id}", headers={"X-Api-Key": api_key}) todos.raise_for_status() From 2f2eb91f6c416ea70a9ede27e14f05737fc90819 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 4 Sep 2023 20:13:08 +0200 Subject: [PATCH 68/85] chore: enforce protocol type checking for app instance --- .../event_handler/api_gateway.py | 24 ++------------ .../event_handler/middlewares/__init__.py | 4 +-- .../event_handler/middlewares/base.py | 27 +++++++++++----- aws_lambda_powertools/event_handler/types.py | 6 ++-- .../src/custom_middlewares.py | 6 ++-- .../src/middleware_getting_started.py | 4 +-- .../middleware_global_middlewares_module.py | 8 ++--- .../event_handler/test_api_middlewares.py | 31 ++++++++++--------- 8 files changed, 53 insertions(+), 57 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index a60bd0a9b4a..5d9e96da504 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -9,26 +9,13 @@ from enum import Enum from functools import partial from http import HTTPStatus -from typing import ( - Any, - Callable, - Dict, - List, - Match, - Optional, - Pattern, - Set, - Tuple, - Type, - Union, -) +from typing import Any, Callable, Dict, List, Match, Optional, Pattern, Set, Tuple, Type, Union from aws_lambda_powertools.event_handler import content_types from aws_lambda_powertools.event_handler.exceptions import NotFoundError, ServiceError from aws_lambda_powertools.shared.cookies import Cookie from aws_lambda_powertools.shared.functions import powertools_dev_is_set from aws_lambda_powertools.shared.json_encoder import Encoder -from aws_lambda_powertools.shared.types import Protocol from aws_lambda_powertools.utilities.data_classes import ( ALBEvent, APIGatewayProxyEvent, @@ -1331,11 +1318,4 @@ def __init__( super().__init__(ProxyEventType.ALBEvent, cors, debug, serializer, strip_prefixes) -class NextMiddlewareCallback(Protocol): - def __call__(self, app: ApiGatewayResolver) -> Response: - """Protocol for callback regardless of next_middleware(app), next(app)""" - ... - - def __name__(self) -> str: # noqa A003 - """Protocol for name of the Middleware""" - ... +# Specialized types defined here due to circular dependency in `.types` diff --git a/aws_lambda_powertools/event_handler/middlewares/__init__.py b/aws_lambda_powertools/event_handler/middlewares/__init__.py index 10c37e8f046..a1f5d5b6cde 100644 --- a/aws_lambda_powertools/event_handler/middlewares/__init__.py +++ b/aws_lambda_powertools/event_handler/middlewares/__init__.py @@ -1,4 +1,4 @@ -from aws_lambda_powertools.event_handler.middlewares.base import BaseMiddlewareHandler +from aws_lambda_powertools.event_handler.middlewares.base import BaseMiddlewareHandler, NextMiddleware from aws_lambda_powertools.event_handler.middlewares.schema_validation import SchemaValidationMiddleware -__all__ = ["BaseMiddlewareHandler", "SchemaValidationMiddleware"] +__all__ = ["BaseMiddlewareHandler", "SchemaValidationMiddleware", "NextMiddleware"] diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index d04c06edba9..ce22f736520 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -1,12 +1,23 @@ from abc import ABC, abstractmethod -from typing import Any, Callable, Generic, TypeVar +from typing import Generic -from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response +from typing_extensions import Protocol -EventHandlerResolver = TypeVar("EventHandlerResolver", bound=ApiGatewayResolver) +from aws_lambda_powertools.event_handler.api_gateway import Response +from aws_lambda_powertools.event_handler.types import EventHandlerInstance -class BaseMiddlewareHandler(Generic[EventHandlerResolver], ABC): +class NextMiddleware(Protocol): + def __call__(self, app: EventHandlerInstance) -> Response: + """Protocol for callback regardless of next_middleware(app), get_response(app) etc""" + ... + + def __name__(self) -> str: # noqa A003 + """Protocol for name of the Middleware""" + ... + + +class BaseMiddlewareHandler(Generic[EventHandlerInstance], ABC): """ Base class for Middleware Handlers @@ -69,15 +80,15 @@ class BaseMiddlewareHandler(Generic[EventHandlerResolver], ABC): """ @abstractmethod - def handler(self, app: EventHandlerResolver, next_middleware: Callable[..., Any]) -> Response: + def handler(self, app: EventHandlerInstance, next_middleware: NextMiddleware) -> Response: """ The Middleware Handler Parameters ---------- - app: EventHandlerResolver + app: EventHandlerInstance An instance of an Event Handler that implements ApiGatewayResolver - next_middleware: Callable[..., Any] + next_middleware: NextMiddleware The next middleware handler in the chain Returns @@ -92,7 +103,7 @@ def handler(self, app: EventHandlerResolver, next_middleware: Callable[..., Any] def __name__(self) -> str: # noqa A003 return str(self.__class__.__name__) - def __call__(self, app: EventHandlerResolver, next_middleware: Callable[..., Any]) -> Response: + def __call__(self, app: EventHandlerInstance, next_middleware: NextMiddleware) -> Response: """ The Middleware handler function. diff --git a/aws_lambda_powertools/event_handler/types.py b/aws_lambda_powertools/event_handler/types.py index d584549f95d..11cd146a57a 100644 --- a/aws_lambda_powertools/event_handler/types.py +++ b/aws_lambda_powertools/event_handler/types.py @@ -1,3 +1,5 @@ -from aws_lambda_powertools.event_handler.api_gateway import NextMiddlewareCallback +from typing import TypeVar -__all__ = ["NextMiddlewareCallback"] +from aws_lambda_powertools.event_handler import ApiGatewayResolver + +EventHandlerInstance = TypeVar("EventHandlerInstance", bound=ApiGatewayResolver) diff --git a/examples/event_handler_rest/src/custom_middlewares.py b/examples/event_handler_rest/src/custom_middlewares.py index a369210855f..7f6e22f16a9 100644 --- a/examples/event_handler_rest/src/custom_middlewares.py +++ b/examples/event_handler_rest/src/custom_middlewares.py @@ -1,12 +1,12 @@ from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import ApiGatewayResolver, Response -from aws_lambda_powertools.event_handler.api_gateway import NextMiddlewareCallback from aws_lambda_powertools.event_handler.exceptions import BadRequestError, InternalServerError, ServiceError +from aws_lambda_powertools.event_handler.middlewares import NextMiddleware logger = Logger() -def validate_correlation_id(app: ApiGatewayResolver, next_middleware: NextMiddlewareCallback) -> Response: +def validate_correlation_id(app: ApiGatewayResolver, next_middleware: NextMiddleware) -> 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.") @@ -15,7 +15,7 @@ def validate_correlation_id(app: ApiGatewayResolver, next_middleware: NextMiddle return next_middleware(app) -def sanitise_exceptions(app: ApiGatewayResolver, next_middleware: NextMiddlewareCallback) -> Response: +def sanitise_exceptions(app: ApiGatewayResolver, next_middleware: NextMiddleware) -> Response: try: # Get the Result from the next middleware result = next_middleware(app) diff --git a/examples/event_handler_rest/src/middleware_getting_started.py b/examples/event_handler_rest/src/middleware_getting_started.py index c8417cad111..6968c85e882 100644 --- a/examples/event_handler_rest/src/middleware_getting_started.py +++ b/examples/event_handler_rest/src/middleware_getting_started.py @@ -2,13 +2,13 @@ from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response -from aws_lambda_powertools.event_handler.types import NextMiddlewareCallback +from aws_lambda_powertools.event_handler.middlewares import NextMiddleware app = APIGatewayRestResolver() logger = Logger() -def inject_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback) -> Response: +def inject_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMiddleware) -> 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 diff --git a/examples/event_handler_rest/src/middleware_global_middlewares_module.py b/examples/event_handler_rest/src/middleware_global_middlewares_module.py index b3638a2bfea..81b83c868ad 100644 --- a/examples/event_handler_rest/src/middleware_global_middlewares_module.py +++ b/examples/event_handler_rest/src/middleware_global_middlewares_module.py @@ -1,11 +1,11 @@ from aws_lambda_powertools import Logger from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response -from aws_lambda_powertools.event_handler.types import NextMiddlewareCallback +from aws_lambda_powertools.event_handler.middlewares import NextMiddleware logger = Logger() -def log_request_response(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback) -> Response: +def log_request_response(app: APIGatewayRestResolver, next_middleware: NextMiddleware) -> Response: logger.info("Incoming request", path=app.current_event.path, request=app.current_event.raw_event) result = next_middleware(app) @@ -14,7 +14,7 @@ def log_request_response(app: APIGatewayRestResolver, next_middleware: NextMiddl return result -def inject_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback) -> Response: +def inject_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMiddleware) -> 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 @@ -32,7 +32,7 @@ def inject_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMidd return result -def enforce_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMiddlewareCallback) -> Response: +def enforce_correlation_id(app: APIGatewayRestResolver, next_middleware: NextMiddleware) -> 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)! diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index 1eaadad5ec1..8db570d699a 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -6,13 +6,16 @@ ApiGatewayResolver, APIGatewayRestResolver, BaseRouter, - NextMiddlewareCallback, ProxyEventType, Response, Router, ) from aws_lambda_powertools.event_handler.exceptions import BadRequestError -from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler, SchemaValidationMiddleware +from aws_lambda_powertools.event_handler.middlewares import ( + BaseMiddlewareHandler, + NextMiddleware, + SchemaValidationMiddleware, +) from tests.functional.utils import load_event API_REST_EVENT = load_event("apiGatewayProxyEvent.json") @@ -29,7 +32,7 @@ ) def test_route_with_middleware(app: BaseRouter, event): # define custom middleware to inject new argument - "custom" - def middleware_1(app: BaseRouter, next_middleware: NextMiddlewareCallback): + def middleware_1(app: BaseRouter, next_middleware: NextMiddleware): # add additional data to Router Context app.append_context(custom="custom") response = next_middleware(app) @@ -37,7 +40,7 @@ def middleware_1(app: BaseRouter, next_middleware: NextMiddlewareCallback): return response # define custom middleware to inject new argument - "another_one" - def middleware_2(app: BaseRouter, next_middleware: NextMiddlewareCallback): + def middleware_2(app: BaseRouter, next_middleware: NextMiddleware): # add additional data to Router Context app.append_context(another_one=6) response = next_middleware(app) @@ -84,7 +87,7 @@ def get_lambda() -> Response: ) def test_with_router_middleware(app: BaseRouter, event, other_event): # define custom middleware to inject new argument - "custom" - def global_middleware(app: BaseRouter, next_middleware: NextMiddlewareCallback): + def global_middleware(app: BaseRouter, next_middleware: NextMiddleware): # add custom data to context app.append_context(custom="custom") response = next_middleware(app) @@ -92,7 +95,7 @@ def global_middleware(app: BaseRouter, next_middleware: NextMiddlewareCallback): return response # define custom middleware to inject new argument - "another_one" - def middleware_2(app: BaseRouter, next_middleware: NextMiddlewareCallback): + def middleware_2(app: BaseRouter, next_middleware: NextMiddleware): # add data to resolver context app.append_context(another_one=6) response = next_middleware(app) @@ -143,7 +146,7 @@ def get_other_lambda() -> Response: ], ) def test_dynamic_route_with_middleware(app: BaseRouter, event): - def middleware_one(app: BaseRouter, next_middleware: NextMiddlewareCallback): + def middleware_one(app: BaseRouter, next_middleware: NextMiddleware): # inject data into the resolver context app.append_context(injected="injected_value") response = next_middleware(app) @@ -182,12 +185,12 @@ def middleware_one(app: BaseRouter, next_middleware): return response - def early_return_middleware(app: BaseRouter, next_middleware: NextMiddlewareCallback): + def early_return_middleware(app: BaseRouter, next_middleware: NextMiddleware): assert app.context.get("injected") == "injected_value" return Response(400, content_types.TEXT_HTML, "bad_response") - def not_executed_middleware(app: BaseRouter, next_middleware: NextMiddlewareCallback): + def not_executed_middleware(app: BaseRouter, next_middleware: NextMiddleware): # This should never be executed - if it is an excpetion will be raised raise NotImplementedError() @@ -310,19 +313,19 @@ def post_lambda() -> Response: ], ) def test_middleware_short_circuit_via_httperrors(app: BaseRouter, event): - def middleware_one(app: BaseRouter, next_middleware: NextMiddlewareCallback): + def middleware_one(app: BaseRouter, next_middleware: NextMiddleware): # inject a variable into the kwargs of the middleware chain app.append_context(injected="injected_value") response = next_middleware(app) return response - def early_return_middleware(app: BaseRouter, next_middleware: NextMiddlewareCallback): + def early_return_middleware(app: BaseRouter, next_middleware: NextMiddleware): # ensure "injected" context variable is passed in by middleware_one assert app.context.get("injected") == "injected_value" raise BadRequestError("bad_response") - def not_executed_middleware(app: BaseRouter, next_middleware: NextMiddlewareCallback): + def not_executed_middleware(app: BaseRouter, next_middleware: NextMiddleware): # This should never be executed - if it is an excpetion will be raised raise NotImplementedError() @@ -373,7 +376,7 @@ def router_middleware(app: BaseRouter, next_middleware): to_inject: str = "injected_value" - def middleware_one(app: BaseRouter, next_middleware: NextMiddlewareCallback): + def middleware_one(app: BaseRouter, next_middleware: NextMiddleware): # inject a variable into the kwargs of the middleware chain app.append_context(injected=to_inject) response = next_middleware(app) @@ -406,7 +409,7 @@ def __init__(self, header: str): super().__init__() self.header = header - def handler(self, app: ApiGatewayResolver, get_response: NextMiddlewareCallback, **kwargs) -> Response: + def handler(self, app: ApiGatewayResolver, get_response: NextMiddleware, **kwargs) -> Response: request_id = app.current_event.request_context.request_id # type: ignore[attr-defined] # using REST event in a base Resolver # noqa: E501 correlation_id = app.current_event.get_header_value( name=self.header, From 03708bbfa2cb0a79e3a23ff22bd06dba0c933008 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 4 Sep 2023 20:40:41 +0200 Subject: [PATCH 69/85] docs: complete extending middlewares section Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 16 ++++++- .../src/middleware_extending_middlewares.py | 47 +++++++++++++++++++ 2 files changed, 62 insertions(+), 1 deletion(-) create mode 100644 examples/event_handler_rest/src/middleware_extending_middlewares.py diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 056c2282e73..40008870e11 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -539,7 +539,21 @@ While there isn't anything special on how to use [`try/catch`](https://docs.pyth #### Extending middlewares -!!! todo "Explain how to create a middleware that accepts configuration with `BaseMiddlewareHandler`" +You can implement `BaseMiddlewareHandler` interface to create middlewares that accept configuration, or perform complex operations (_see [being a good citizen section](#being-a-good-citizen)_). + +As a practical example, let's refactor our correlation ID middleware so it accepts a custom HTTP Header to look for. + +```python hl_lines="5 11 23 36" title="Authoring class-based middlewares with BaseMiddlewareHandler" +--8<-- "examples/event_handler_rest/src/middleware_extending_middlewares.py" +``` + +1. You can add any constructor argument like you normally would +2. We implement `handler` just like we [did before](#middleware) with the only exception of the `self` argument, since it's a method. +3. Get response from the next middleware (if any) or from `/todos` route. +4. Register an instance of `CorrelationIdMiddleware`. + +!!! note "Class-based **vs** function-based middlewares" + When registering a middleware, we expect a callable in both cases. For class-based middlewares, `BaseMiddlewareHandler` is doing the work of calling your `handler` method with the correct parameters, hence why we expect an instance of it. #### Being a good citizen diff --git a/examples/event_handler_rest/src/middleware_extending_middlewares.py b/examples/event_handler_rest/src/middleware_extending_middlewares.py new file mode 100644 index 00000000000..e492caacf47 --- /dev/null +++ b/examples/event_handler_rest/src/middleware_extending_middlewares.py @@ -0,0 +1,47 @@ +import requests + +from aws_lambda_powertools import Logger +from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response +from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler, NextMiddleware + +app = APIGatewayRestResolver() +logger = Logger() + + +class CorrelationIdMiddleware(BaseMiddlewareHandler): + def __init__(self, header: str): # (1)! + """Extract and inject correlation ID in response + + Parameters + ---------- + header : str + HTTP Header to extract correlation ID + """ + super().__init__() + self.header = header + + def handler(self, app: APIGatewayRestResolver, next_middleware: NextMiddleware) -> Response: # (2)! + request_id = app.current_event.request_context.request_id + correlation_id = app.current_event.get_header_value( + name=self.header, + default_value=request_id, + ) + + response = next_middleware(app) # (3)! + response.headers[self.header] = correlation_id + + return response + + +@app.get("/todos", middlewares=[CorrelationIdMiddleware(header="x-correlation-id")]) # (4)! +def get_todos(): + todos: requests.Response = requests.get("https://jsonplaceholder.typicode.com/todos") + todos.raise_for_status() + + # for brevity, we'll limit to the first 10 only + return {"todos": todos.json()[:10]} + + +@logger.inject_lambda_context +def lambda_handler(event, context): + return app.resolve(event, context) From 5dc57194d1b810eec01da075b084a5b7f9e7e228 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 4 Sep 2023 20:43:11 +0200 Subject: [PATCH 70/85] fix: remove schema validation export due to optional dependency Signed-off-by: heitorlessa --- aws_lambda_powertools/event_handler/middlewares/__init__.py | 3 +-- tests/functional/event_handler/test_api_middlewares.py | 2 ++ 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/aws_lambda_powertools/event_handler/middlewares/__init__.py b/aws_lambda_powertools/event_handler/middlewares/__init__.py index a1f5d5b6cde..068ce9c04b7 100644 --- a/aws_lambda_powertools/event_handler/middlewares/__init__.py +++ b/aws_lambda_powertools/event_handler/middlewares/__init__.py @@ -1,4 +1,3 @@ from aws_lambda_powertools.event_handler.middlewares.base import BaseMiddlewareHandler, NextMiddleware -from aws_lambda_powertools.event_handler.middlewares.schema_validation import SchemaValidationMiddleware -__all__ = ["BaseMiddlewareHandler", "SchemaValidationMiddleware", "NextMiddleware"] +__all__ = ["BaseMiddlewareHandler", "NextMiddleware"] diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index 8db570d699a..40cf64edec3 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -14,6 +14,8 @@ from aws_lambda_powertools.event_handler.middlewares import ( BaseMiddlewareHandler, NextMiddleware, +) +from aws_lambda_powertools.event_handler.middlewares.schema_validation import ( SchemaValidationMiddleware, ) from tests.functional.utils import load_event From f7800b2cecddea90e8f5832761ed653552b4e9c7 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 4 Sep 2023 21:31:04 +0200 Subject: [PATCH 71/85] refactor: improve docstrings for schema validation; typing Signed-off-by: heitorlessa --- .../middlewares/schema_validation.py | 80 +++++++++++++++---- 1 file changed, 63 insertions(+), 17 deletions(-) diff --git a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py index be231f25c14..66be47a48f3 100644 --- a/aws_lambda_powertools/event_handler/middlewares/schema_validation.py +++ b/aws_lambda_powertools/event_handler/middlewares/schema_validation.py @@ -1,9 +1,10 @@ import logging -from typing import Any, Callable, Dict, Optional +from typing import Dict, Optional -from aws_lambda_powertools.event_handler.api_gateway import ApiGatewayResolver, Response +from aws_lambda_powertools.event_handler.api_gateway import Response from aws_lambda_powertools.event_handler.exceptions import BadRequestError, InternalServerError -from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler +from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler, NextMiddleware +from aws_lambda_powertools.event_handler.types import EventHandlerInstance from aws_lambda_powertools.utilities.validation import validate from aws_lambda_powertools.utilities.validation.exceptions import InvalidSchemaFormatError, SchemaValidationError @@ -11,9 +12,38 @@ class SchemaValidationMiddleware(BaseMiddlewareHandler): - """ - Validates the API request body against the provided schema. + """Middleware to validate API request and response against JSON Schema using the [Validation utility](https://docs.powertools.aws.dev/lambda/python/latest/utilities/validation/). + + Examples + -------- + **Validating incoming event** + + ```python + import requests + + from aws_lambda_powertools import Logger + from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response + from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler, NextMiddleware + from aws_lambda_powertools.event_handler.middlewares.schema_validation import SchemaValidationMiddleware + + app = APIGatewayRestResolver() + logger = Logger() + json_schema_validation = SchemaValidationMiddleware(inbound_schema=INCOMING_JSON_SCHEMA) + + @app.get("/todos", middlewares=[json_schema_validation]) + def get_todos(): + todos: requests.Response = requests.get("https://jsonplaceholder.typicode.com/todos") + todos.raise_for_status() + + # for brevity, we'll limit to the first 10 only + return {"todos": todos.json()[:10]} + + + @logger.inject_lambda_context + def lambda_handler(event, context): + return app.resolve(event, context) + ``` """ def __init__( @@ -23,6 +53,18 @@ def __init__( outbound_schema: Optional[Dict] = None, outbound_formats: Optional[Dict] = None, ): + """See [Validation utility](https://docs.powertools.aws.dev/lambda/python/latest/utilities/validation/) docs for examples on all parameters. + + Parameters + ---------- + inbound_schema : Dict + JSON Schema to validate incoming event + inbound_formats : Optional[Dict], optional + Custom formats containing a key (e.g. int64) and a value expressed as regex or callback returning bool, by default None + JSON Schema to validate outbound event, by default None + outbound_formats : Optional[Dict], optional + Custom formats containing a key (e.g. int64) and a value expressed as regex or callback returning bool, by default None + """ # noqa: E501 super().__init__() self.inbound_schema = inbound_schema self.inbound_formats = inbound_formats @@ -43,19 +85,24 @@ def bad_config(self, error: InvalidSchemaFormatError) -> Response: logger.debug(f"Invalid Schema Format: {error}") raise InternalServerError("Internal Server Error") - def handler(self, app: ApiGatewayResolver, next_middleware: Callable[..., Any]) -> Response: - """ - Validate using Powertools validate() utility. - - Return HTTP 400 Response if validation fails. - Return HTTP 500 Response if validation fails due to invalid schema format. + def handler(self, app: EventHandlerInstance, next_middleware: NextMiddleware) -> Response: + """Validates incoming JSON payload (body) against JSON Schema provided. - Return the next middleware response if validation passes. + Parameters + ---------- + app : EventHandlerInstance + An instance of an Event Handler + next_middleware : NextMiddleware + Callable to get response from the next middleware or route handler in the chain - :param app: The ApiGatewayResolver instance - :param next_middleware: The original response - :return: The original response or HTTP 400 Response or HTTP 500 Response. + Returns + ------- + Response + It can return three types of response objects + - Original response: Propagates HTTP response returned from the next middleware if validation succeeds + - HTTP 400: Payload or response failed JSON Schema validation + - HTTP 500: JSON Schema provided has incorrect format """ try: validate(event=app.current_event.json_body, schema=self.inbound_schema, formats=self.inbound_formats) @@ -64,8 +111,7 @@ def handler(self, app: ApiGatewayResolver, next_middleware: Callable[..., Any]) except InvalidSchemaFormatError as error: return self.bad_config(error) - # return next middleware response if validation passes. - result: Response = next_middleware(app) + result = next_middleware(app) if self.outbound_formats is not None: try: From 6f63b4fe22b202ed71ee94b7ae8dd20660c452a8 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 4 Sep 2023 21:31:33 +0200 Subject: [PATCH 72/85] chore: leftover from previous circular dep issue Signed-off-by: heitorlessa --- aws_lambda_powertools/event_handler/api_gateway.py | 3 --- 1 file changed, 3 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 5d9e96da504..e87b38e9435 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -1316,6 +1316,3 @@ def __init__( ): """Amazon Application Load Balancer (ALB) resolver""" super().__init__(ProxyEventType.ALBEvent, cors, debug, serializer, strip_prefixes) - - -# Specialized types defined here due to circular dependency in `.types` From 03d15fad36a82757e9e9697b79d2712a5e0d5edb Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Mon, 4 Sep 2023 21:40:45 +0200 Subject: [PATCH 73/85] docs: add native middleware section Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 40008870e11..adc46e90c8f 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -555,6 +555,14 @@ As a practical example, let's refactor our correlation ID middleware so it accep !!! note "Class-based **vs** function-based middlewares" When registering a middleware, we expect a callable in both cases. For class-based middlewares, `BaseMiddlewareHandler` is doing the work of calling your `handler` method with the correct parameters, hence why we expect an instance of it. +#### Native middlewares + +These are native middlewares that may become native features depending on customer demand. + +| Middleware | Purpose | +| ---------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| [SchemaValidationMiddleware](/api/event_handler/middlewares/schema_validation.html){target="_blank"} | Validates API request body and response against JSON Schema, using [Validation utility](../../utilities/validation.md){target="_blank"} | + #### Being a good citizen Middlewares can add subtle improvements to request/response processing, but also add significant complexity if you're not careful. From b7bcb0884eb0e1f6cdaeaaf44e21f1e065e8216c Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Tue, 5 Sep 2023 09:51:36 +1000 Subject: [PATCH 74/85] docs - refactor references of with kwargs to , remove **lwargs references. --- docs/core/event_handler/api_gateway.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index adc46e90c8f..50d9201cbe1 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -370,7 +370,7 @@ stateDiagram EventHandler: GET /todo Before: Before response - Next: get_response() + Next: next_middleware() MiddlewareLoop: Middleware loop AfterResponse: After response MiddlewareFinished: Modified response @@ -394,8 +394,7 @@ A middleware is a function you register per route to **intercept** or **enrich** Each middleware function receives the following arguments: 1. **app**. An Event Handler instance so you can access incoming request information, Lambda context, etc. -2. **get_response**. A function to get the next middleware or route's response. -3. **`**kwargs`**. Middleware keyword arguments that are propagated in the chain. +2. **next_middleware**. A function to get the next middleware or route's response. Here's a sample middleware that extracts and injects correlation ID, using `APIGatewayRestResolver` (works for any [Resolver](#event-resolvers)): @@ -406,7 +405,7 @@ Here's a sample middleware that extracts and injects correlation ID, using `APIG ``` 1. You can access current request like you normally would. - 2. [Shared context is available](#sharing-contextual-data) to any middleware, Router and App instances.

Alternatively, you can use `**context` kwargs which will only be available for middlewares. + 2. [Shared context is available](#sharing-contextual-data) to any middleware, Router and App instances. 3. Get response from the next middleware (if any) or from `/todos` route. 4. You can manipulate headers, body, or status code before returning it. 5. Register one or more middlewares in order of execution. @@ -506,7 +505,7 @@ While there isn't anything special on how to use [`try/catch`](https://docs.pyth === "Unhandled exception from route handler" - An exception wasn't caught by any middleware during `get_response()` block, therefore it propagates all the way back to the client as HTTP 500. + An exception wasn't caught by any middleware during `next_middleware()` block, therefore it propagates all the way back to the client as HTTP 500.
![Unhandled exceptions](../../media/middlewares_unhandled_route_exception-light.svg#only-light) @@ -570,7 +569,7 @@ Middlewares can add subtle improvements to request/response processing, but also Keep the following in mind when authoring middlewares for Event Handler: 1. **Use built-in features over middlewares**. We include built-in features like [CORS](#cors), [compression](#compress), [binary responses](#binary-responses), [global exception handling](#exception-handling), and [debug mode](#debug-mode) to reduce the need for middlewares. -2. **Call the next middleware**. Return the result of `get_response(app, **kwargs)`, or a [Response object](#fine-grained-responses) when you want to [return early](#returning-early). +2. **Call the next middleware**. Return the result of `next_middleware(app)`, or a [Response object](#fine-grained-responses) when you want to [return early](#returning-early). 3. **Keep a lean scope**. Focus on a single task per middleware to ease composability and maintenance. In [debug mode](#debug-mode), we also print out the order middlewares will be triggered to ease operations. 4. **Catch your own exceptions**. Catch and handle known exceptions to your logic. Unless you want to raise [HTTP Errors](#raising-http-errors), or propagate specific exceptions to the client. To catch all and any exceptions, we recommend you use the [exception_handler](#exception-handling) decorator. 5. **Use context to share data**. Use `app.append_context` to [share contextual data](#sharing-contextual-data) between middlewares and route handlers, and `app.context.get(key)` to fetch them. We clear all contextual data at the end of every request. From 7ca4a3a3c5a59ad04be7559e3f41dcf14cdf14f0 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Tue, 5 Sep 2023 08:41:45 +0200 Subject: [PATCH 75/85] chore: add middleware order test Signed-off-by: heitorlessa --- .../event_handler/test_api_middlewares.py | 106 +++++++++++++----- 1 file changed, 75 insertions(+), 31 deletions(-) diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index 40cf64edec3..c052d2edb36 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -1,3 +1,5 @@ +from typing import List + import pytest from aws_lambda_powertools.event_handler import content_types @@ -18,6 +20,7 @@ from aws_lambda_powertools.event_handler.middlewares.schema_validation import ( SchemaValidationMiddleware, ) +from aws_lambda_powertools.event_handler.types import EventHandlerInstance from tests.functional.utils import load_event API_REST_EVENT = load_event("apiGatewayProxyEvent.json") @@ -354,54 +357,95 @@ def get_lambda(my_id: str, name: str) -> Response: (APIGatewayHttpResolver(), API_RESTV2_EVENT), ], ) -def test_api_gateway_app_router_with_middlewares(app: BaseRouter, event): - # GIVEN a Router with registered routes +def test_api_gateway_middleware_order_with_include_router_last(app: EventHandlerInstance, event): + # GIVEN two global middlewares: one for App and one for Router router = Router() - def app_middleware(app: BaseRouter, next_middleware): - # inject a variable into the resolver context - app.append_context(app_injected="app_value") - response = next_middleware(app) + def global_app_middleware(app: EventHandlerInstance, next_middleware: NextMiddleware): + middleware_order: List[str] = router.context.get("middleware_order", []) + middleware_order.append("app") - return response + app.append_context(middleware_order=middleware_order) + return next_middleware(app) - app.use(middlewares=[app_middleware]) + def global_router_middleware(router: EventHandlerInstance, next_middleware: NextMiddleware): + middleware_order: List[str] = router.context.get("middleware_order", []) + middleware_order.append("router") - def router_middleware(app: BaseRouter, next_middleware): - # inject a variable into the resolver context - app.append_context(router_injected="router_value") - response = next_middleware(app) + router.append_context(middleware_order=middleware_order) + return next_middleware(app) - return response + @router.get("/my/path") + def dummy_route(): + middleware_order = app.context["middleware_order"] - router.use(middlewares=[router_middleware]) + assert middleware_order[0] == "app" + assert middleware_order[1] == "router" - to_inject: str = "injected_value" + return Response(status_code=200, body="works!") - def middleware_one(app: BaseRouter, next_middleware: NextMiddleware): - # inject a variable into the kwargs of the middleware chain - app.append_context(injected=to_inject) - response = next_middleware(app) + # WHEN App global middlewares are registered first + # followed by include_router - return response + router.use([global_router_middleware]) # mimics App importing Router + app.include_router(router) + app.use([global_app_middleware]) - @router.get("/my/path", middlewares=[middleware_one]) - def get_api_route(): - # make sure value is injected by middleware_one - injected: str = app.context.get("injected") - assert injected == to_inject - assert app.context.get("router_injected") == "router_value" - assert app.context.get("app_injected") == "app_value" + # THEN resolving a request should start processing global Router middlewares first + # due to insertion order + result = app(event, {}) + + assert result["statusCode"] == 200 - return Response(200, content_types.TEXT_HTML, injected) +@pytest.mark.parametrize( + "app, event", + [ + (ApiGatewayResolver(proxy_type=ProxyEventType.APIGatewayProxyEvent), API_REST_EVENT), + (APIGatewayRestResolver(), API_REST_EVENT), + (APIGatewayHttpResolver(), API_RESTV2_EVENT), + ], +) +def test_api_gateway_middleware_order_with_include_router_first(app: EventHandlerInstance, event): + # GIVEN two global middlewares: one for App and one for Router + router = Router() + + def global_app_middleware(app: EventHandlerInstance, next_middleware: NextMiddleware): + middleware_order: List[str] = router.context.get("middleware_order", []) + middleware_order.append("app") + + app.append_context(middleware_order=middleware_order) + return next_middleware(app) + + def global_router_middleware(router: EventHandlerInstance, next_middleware: NextMiddleware): + middleware_order: List[str] = router.context.get("middleware_order", []) + middleware_order.append("router") + + router.append_context(middleware_order=middleware_order) + return next_middleware(app) + + @router.get("/my/path") + def dummy_route(): + middleware_order = app.context["middleware_order"] + + assert middleware_order[0] == "router" + assert middleware_order[1] == "app" + + return Response(status_code=200, body="works!") + + # WHEN App include router middlewares first + # followed by App global middlewares registration + + router.use([global_router_middleware]) # mimics App importing Router app.include_router(router) - # WHEN calling the event handler after applying routes from router object + + app.use([global_app_middleware]) + + # THEN resolving a request should start processing global Router middlewares first + # due to insertion order result = app(event, {}) - # THEN process event correctly assert result["statusCode"] == 200 - assert result["body"] == to_inject def test_class_based_middleware(): From 870545abbea993baba0df49e8d45a1489b5f63aa Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Tue, 5 Sep 2023 08:44:22 +0200 Subject: [PATCH 76/85] refactor: add debug log Signed-off-by: heitorlessa --- aws_lambda_powertools/event_handler/api_gateway.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index e87b38e9435..844fccd8b89 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -1189,10 +1189,10 @@ def include_router(self, router: "Router", prefix: Optional[str] = None) -> None # Add reference to parent ApiGatewayResolver to support use cases where people subclass it to add custom logic router.api_resolver = self - # Merge app and router context + logger.debug("Merging App context with Router context") self.context.update(**router.context) - # Add router middlewares to parent ApiGatewayResolver + logger.debug("Appending Router middlewares into App middlewares.") self._router_middlewares = self._router_middlewares + router._router_middlewares # use pointer to allow context clearance after event is processed e.g., resolve(evt, ctx) @@ -1206,7 +1206,7 @@ def include_router(self, router: "Router", prefix: Optional[str] = None) -> None rule = prefix if rule == "/" else f"{prefix}{rule}" new_route = (rule, *route[1:]) - # Middlewares are stored by route seperately - must grab them to include + # Middlewares are stored by route separately - must grab them to include middlewares = router._routes_with_middleware.get(new_route) # Need to use "type: ignore" here since mypy does not like a named parameter after From 44cb04b8d7088395e316b86257e1d3a00a311f26 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Tue, 5 Sep 2023 08:45:20 +0200 Subject: [PATCH 77/85] docs: move staging area to router section Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 75 ++++++++++++-------------- 1 file changed, 34 insertions(+), 41 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 50d9201cbe1..b8a35ab8d76 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -574,38 +574,6 @@ Keep the following in mind when authoring middlewares for Event Handler: 4. **Catch your own exceptions**. Catch and handle known exceptions to your logic. Unless you want to raise [HTTP Errors](#raising-http-errors), or propagate specific exceptions to the client. To catch all and any exceptions, we recommend you use the [exception_handler](#exception-handling) decorator. 5. **Use context to share data**. Use `app.append_context` to [share contextual data](#sharing-contextual-data) between middlewares and route handlers, and `app.context.get(key)` to fetch them. We clear all contextual data at the end of every request. -#### Staging area - -**This should go under the Router area since we haven't introduced it yet** - -Middleware functions used in the Router instance will apply to all API routes and will always be processed first in the order they are added to the Router. Route specific middleware added to each route will then be processed in the order they were added in the route definition. - -???+ tip - **Router Middleware processing Order** - - 1. Global middlewares defined on the parent Router - 2. Route specific Middlewares - - To maximize the re-usability of your middleware functions we recommend using the **BaseRouter** or **Router** classes providing the **current_event** object contains the required fields for your middleware. - -???+ warning "Ensure your middleware calls the Next one in the chain" - The middleware stack processing relies on each middleware function calling the next and also returning the reponse or raising an exception. If you do not pass control to the next middleware function in the chain, your API route handler will never be called. - -=== "route_middleware.py" - ```python hl_lines="9 16" - --8<-- "examples/event_handler_rest/src/route_middleware.py" - ``` - -=== "all_routes_middleware.py" - ```python hl_lines="9 15" - --8<-- "examples/event_handler_rest/src/all_routes_middleware.py" - ``` - -=== "custom_middlewares.py" - ```python hl_lines="12 14 18 21 23" - --8<-- "examples/event_handler_rest/src/custom_middlewares.py" - ``` - ### Fine grained responses You can use the `Response` class to have full control over the response. For example, you might want to add additional headers, cookies, or set a custom Content-type. @@ -743,15 +711,6 @@ Let's assume you have `split_route.py` as your Lambda function entrypoint and ro --8<-- "examples/event_handler_rest/src/split_route.py" ``` -#### Split Router Middleware - -The application of middleware functions for split routers is the same as using the main Resolver classes. When the split routes are combined in the API Rest resolver all Router based and route base middleware will be merged into the parent instance. - -???+ info "Split Router Middleware processing Order" - 1. Global Middleware defined on the parent Router - 2. Global Middleware for each split Router, in the order they are included - 3. Route specific Middlewares - #### Route prefix In the previous example, `split_route_module.py` routes had a `/todos` prefix. This might grow over time and become repetitive. @@ -838,6 +797,40 @@ This is a sample project layout for a monolithic function with routes split in d └── test_main.py # functional tests for the main lambda handler ``` +#### DRAFT Router Middlewares + +Middleware functions used in the Router instance will apply to all API routes and will always be processed first in the order they are added to the Router. Route specific middleware added to each route will then be processed in the order they were added in the route definition. + +???+ tip + **Router Middleware processing Order** + + 1. Global middlewares defined on the parent Router + 2. Route specific Middlewares + + To maximize the re-usability of your middleware functions we recommend using the **BaseRouter** or **Router** classes providing the **current_event** object contains the required fields for your middleware. + +=== "route_middleware.py" + ```python hl_lines="9 16" + --8<-- "examples/event_handler_rest/src/route_middleware.py" + ``` + +=== "all_routes_middleware.py" + ```python hl_lines="9 15" + --8<-- "examples/event_handler_rest/src/all_routes_middleware.py" + ``` + +=== "custom_middlewares.py" + ```python hl_lines="12 14 18 21 23" + --8<-- "examples/event_handler_rest/src/custom_middlewares.py" + ``` + +The application of middleware functions for split routers is the same as using the main Resolver classes. When the split routes are combined in the API Rest resolver all Router based and route base middleware will be merged into the parent instance. + +???+ info "Split Router Middleware processing Order" + 1. Global Middleware defined on the parent Router + 2. Global Middleware for each split Router, in the order they are included + 3. Route specific Middlewares + ### Considerations This utility is optimized for fast startup, minimal feature set, and to quickly on-board customers familiar with frameworks like Flask — it's not meant to be a fully fledged framework. From 4e1a6543f479e9860cb6a45023db75e41cbd8aa4 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Tue, 5 Sep 2023 08:51:56 +0200 Subject: [PATCH 78/85] fix: remove leftover order from middleware order test Signed-off-by: heitorlessa --- tests/functional/event_handler/test_api_middlewares.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index c052d2edb36..df4c0a933ec 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -388,8 +388,8 @@ def dummy_route(): # followed by include_router router.use([global_router_middleware]) # mimics App importing Router - app.include_router(router) app.use([global_app_middleware]) + app.include_router(router) # THEN resolving a request should start processing global Router middlewares first # due to insertion order From 19eaa733b748ba37f45d6c2d95c42d0f1f97c89e Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Wed, 6 Sep 2023 20:53:59 +1000 Subject: [PATCH 79/85] middlewares: reverse internal function rename to ensure no breaking change (just in case) --- aws_lambda_powertools/event_handler/api_gateway.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 844fccd8b89..781bc3ef5b0 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -764,7 +764,7 @@ def _registered_api_adapter( route_args: Dict = app.context.get("_route_args", {}) logger.debug(f"Calling API Route Handler: {route_args}") - return app.to_response(next_middleware(**route_args)) + return app._to_response(next_middleware(**route_args)) class ApiGatewayResolver(BaseRouter): @@ -1077,7 +1077,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, @@ -1148,7 +1148,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: From 592d9dafce1aaf5a6919a20aaeb8ba5acce5f13c Mon Sep 17 00:00:00 2001 From: walmsles <2704782+walmsles@users.noreply.github.com> Date: Wed, 6 Sep 2023 21:24:01 +1000 Subject: [PATCH 80/85] chore(tests): remove typing isues --- .../event_handler/test_api_middlewares.py | 39 +++++++++---------- 1 file changed, 19 insertions(+), 20 deletions(-) diff --git a/tests/functional/event_handler/test_api_middlewares.py b/tests/functional/event_handler/test_api_middlewares.py index df4c0a933ec..8f98b93343f 100644 --- a/tests/functional/event_handler/test_api_middlewares.py +++ b/tests/functional/event_handler/test_api_middlewares.py @@ -7,7 +7,6 @@ APIGatewayHttpResolver, ApiGatewayResolver, APIGatewayRestResolver, - BaseRouter, ProxyEventType, Response, Router, @@ -35,9 +34,9 @@ (APIGatewayHttpResolver(), API_RESTV2_EVENT), ], ) -def test_route_with_middleware(app: BaseRouter, event): +def test_route_with_middleware(app: ApiGatewayResolver, event): # define custom middleware to inject new argument - "custom" - def middleware_1(app: BaseRouter, next_middleware: NextMiddleware): + def middleware_1(app: ApiGatewayResolver, next_middleware: NextMiddleware): # add additional data to Router Context app.append_context(custom="custom") response = next_middleware(app) @@ -45,7 +44,7 @@ def middleware_1(app: BaseRouter, next_middleware: NextMiddleware): return response # define custom middleware to inject new argument - "another_one" - def middleware_2(app: BaseRouter, next_middleware: NextMiddleware): + def middleware_2(app: ApiGatewayResolver, next_middleware: NextMiddleware): # add additional data to Router Context app.append_context(another_one=6) response = next_middleware(app) @@ -90,9 +89,9 @@ def get_lambda() -> Response: ), ], ) -def test_with_router_middleware(app: BaseRouter, event, other_event): +def test_with_router_middleware(app: ApiGatewayResolver, event, other_event): # define custom middleware to inject new argument - "custom" - def global_middleware(app: BaseRouter, next_middleware: NextMiddleware): + def global_middleware(app: ApiGatewayResolver, next_middleware: NextMiddleware): # add custom data to context app.append_context(custom="custom") response = next_middleware(app) @@ -100,7 +99,7 @@ def global_middleware(app: BaseRouter, next_middleware: NextMiddleware): return response # define custom middleware to inject new argument - "another_one" - def middleware_2(app: BaseRouter, next_middleware: NextMiddleware): + def middleware_2(app: ApiGatewayResolver, next_middleware: NextMiddleware): # add data to resolver context app.append_context(another_one=6) response = next_middleware(app) @@ -150,8 +149,8 @@ def get_other_lambda() -> Response: (APIGatewayHttpResolver(), API_RESTV2_EVENT), ], ) -def test_dynamic_route_with_middleware(app: BaseRouter, event): - def middleware_one(app: BaseRouter, next_middleware: NextMiddleware): +def test_dynamic_route_with_middleware(app: ApiGatewayResolver, event): + def middleware_one(app: ApiGatewayResolver, next_middleware: NextMiddleware): # inject data into the resolver context app.append_context(injected="injected_value") response = next_middleware(app) @@ -182,20 +181,20 @@ def get_lambda(my_id: str, name: str) -> Response: (APIGatewayHttpResolver(), API_RESTV2_EVENT), ], ) -def test_middleware_early_return(app: BaseRouter, event): - def middleware_one(app: BaseRouter, next_middleware): +def test_middleware_early_return(app: ApiGatewayResolver, event): + def middleware_one(app: ApiGatewayResolver, next_middleware): # inject a variable into resolver context app.append_context(injected="injected_value") response = next_middleware(app) return response - def early_return_middleware(app: BaseRouter, next_middleware: NextMiddleware): + def early_return_middleware(app: ApiGatewayResolver, next_middleware: NextMiddleware): assert app.context.get("injected") == "injected_value" return Response(400, content_types.TEXT_HTML, "bad_response") - def not_executed_middleware(app: BaseRouter, next_middleware: NextMiddleware): + def not_executed_middleware(app: ApiGatewayResolver, next_middleware: NextMiddleware): # This should never be executed - if it is an excpetion will be raised raise NotImplementedError() @@ -231,7 +230,7 @@ def get_lambda(my_id: str, name: str) -> Response: ), ], ) -def test_pass_schema_validation(app: BaseRouter, event, validation_schema): +def test_pass_schema_validation(app: ApiGatewayResolver, event, validation_schema): @app.post("/my/path", middlewares=[SchemaValidationMiddleware(validation_schema)]) def post_lambda() -> Response: return Response(200, content_types.TEXT_HTML, "path") @@ -261,7 +260,7 @@ def post_lambda() -> Response: ), ], ) -def test_fail_schema_validation(app: BaseRouter, event, validation_schema): +def test_fail_schema_validation(app: ApiGatewayResolver, event, validation_schema): @app.post("/my/path", middlewares=[SchemaValidationMiddleware(validation_schema)]) def post_lambda() -> Response: return Response(200, content_types.TEXT_HTML, "Should not be returned") @@ -295,7 +294,7 @@ def post_lambda() -> Response: ), ], ) -def test_invalid_schema_validation(app: BaseRouter, event): +def test_invalid_schema_validation(app: ApiGatewayResolver, event): @app.post("/my/path", middlewares=[SchemaValidationMiddleware(inbound_schema="schema.json")]) def post_lambda() -> Response: return Response(200, content_types.TEXT_HTML, "Should not be returned") @@ -317,20 +316,20 @@ def post_lambda() -> Response: (APIGatewayHttpResolver(), API_RESTV2_EVENT), ], ) -def test_middleware_short_circuit_via_httperrors(app: BaseRouter, event): - def middleware_one(app: BaseRouter, next_middleware: NextMiddleware): +def test_middleware_short_circuit_via_httperrors(app: ApiGatewayResolver, event): + def middleware_one(app: ApiGatewayResolver, next_middleware: NextMiddleware): # inject a variable into the kwargs of the middleware chain app.append_context(injected="injected_value") response = next_middleware(app) return response - def early_return_middleware(app: BaseRouter, next_middleware: NextMiddleware): + def early_return_middleware(app: ApiGatewayResolver, next_middleware: NextMiddleware): # ensure "injected" context variable is passed in by middleware_one assert app.context.get("injected") == "injected_value" raise BadRequestError("bad_response") - def not_executed_middleware(app: BaseRouter, next_middleware: NextMiddleware): + def not_executed_middleware(app: ApiGatewayResolver, next_middleware: NextMiddleware): # This should never be executed - if it is an excpetion will be raised raise NotImplementedError() From d1508c7b5a441d0026556ba09411266034033ef6 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Thu, 7 Sep 2023 20:02:24 +0200 Subject: [PATCH 81/85] docs: middleware in router Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 54 +++++-------------- .../event_handler_rest/src/split_route.py | 2 +- 2 files changed, 15 insertions(+), 41 deletions(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index b8a35ab8d76..9e47a8a0dfe 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -691,14 +691,19 @@ You can instruct event handler to use a custom serializer to best suit your need ### Split routes with Router -As you grow the number of routes a given Lambda function should handle, it is natural to split routes into separate files to ease maintenance - That's where the `Router` feature is useful. +As you grow the number of routes a given Lambda function should handle, it is natural to either break into smaller Lambda functions, or split routes into separate files to ease maintenance - that's where the `Router` feature is useful. Let's assume you have `split_route.py` as your Lambda function entrypoint and routes in `split_route_module.py`. This is how you'd use the `Router` feature. + + === "split_route_module.py" We import **Router** instead of **APIGatewayRestResolver**; syntax wise is exactly the same. + !!! info + This means all methods, including [middleware](#middleware) will work as usual. + ```python hl_lines="5 13 16 25 28" --8<-- "examples/event_handler_rest/src/split_route_module.py" ``` @@ -707,10 +712,16 @@ Let's assume you have `split_route.py` as your Lambda function entrypoint and ro We use `include_router` method and include all user routers registered in the `router` global object. + !!! note + This method merges routes, [context](#sharing-contextual-data) and [middleware](#middleware) from `Router` into the main resolver instance (`APIGatewayRestResolver()`). + ```python hl_lines="11" --8<-- "examples/event_handler_rest/src/split_route.py" ``` + 1. When using [middleware](#middleware) in both `Router` and main resolver, you can make `Router` middlewares to take precedence by using `include_router` before `app.use()`. + + #### Route prefix In the previous example, `split_route_module.py` routes had a `/todos` prefix. This might grow over time and become repetitive. @@ -748,11 +759,8 @@ You can use specialized router classes according to the type of event that you a You can use `append_context` when you want to share data between your App and Router instances. Any data you share will be available via the `context` dictionary available in your App or Router context. -???+ info - For safety, we always clear any data available in the `context` dictionary after each invocation. - -???+ tip - This can also be useful for middlewares injecting contextual information before a request is processed. +???+ info "We always clear data available in `context` after each invocation." + This can be useful for middlewares injecting contextual information before a request is processed. === "split_route_append_context.py" @@ -797,40 +805,6 @@ This is a sample project layout for a monolithic function with routes split in d └── test_main.py # functional tests for the main lambda handler ``` -#### DRAFT Router Middlewares - -Middleware functions used in the Router instance will apply to all API routes and will always be processed first in the order they are added to the Router. Route specific middleware added to each route will then be processed in the order they were added in the route definition. - -???+ tip - **Router Middleware processing Order** - - 1. Global middlewares defined on the parent Router - 2. Route specific Middlewares - - To maximize the re-usability of your middleware functions we recommend using the **BaseRouter** or **Router** classes providing the **current_event** object contains the required fields for your middleware. - -=== "route_middleware.py" - ```python hl_lines="9 16" - --8<-- "examples/event_handler_rest/src/route_middleware.py" - ``` - -=== "all_routes_middleware.py" - ```python hl_lines="9 15" - --8<-- "examples/event_handler_rest/src/all_routes_middleware.py" - ``` - -=== "custom_middlewares.py" - ```python hl_lines="12 14 18 21 23" - --8<-- "examples/event_handler_rest/src/custom_middlewares.py" - ``` - -The application of middleware functions for split routers is the same as using the main Resolver classes. When the split routes are combined in the API Rest resolver all Router based and route base middleware will be merged into the parent instance. - -???+ info "Split Router Middleware processing Order" - 1. Global Middleware defined on the parent Router - 2. Global Middleware for each split Router, in the order they are included - 3. Route specific Middlewares - ### Considerations This utility is optimized for fast startup, minimal feature set, and to quickly on-board customers familiar with frameworks like Flask — it's not meant to be a fully fledged framework. diff --git a/examples/event_handler_rest/src/split_route.py b/examples/event_handler_rest/src/split_route.py index 6c0933ea08e..b9edc1d0457 100644 --- a/examples/event_handler_rest/src/split_route.py +++ b/examples/event_handler_rest/src/split_route.py @@ -8,7 +8,7 @@ tracer = Tracer() logger = Logger() app = APIGatewayRestResolver() -app.include_router(split_route_module.router) +app.include_router(split_route_module.router) # (1)! # You can continue to use other utilities just as before From aa68e4087a3df8d20e2ebe72e9405e5d2f1d39ea Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Thu, 7 Sep 2023 21:58:52 +0200 Subject: [PATCH 82/85] chore: last cleanups Signed-off-by: heitorlessa --- .../event_handler/api_gateway.py | 78 ++++++++++-------- .../event_handler/middlewares/base.py | 80 +++++++++---------- .../src/all_routes_middleware.py | 31 ------- .../src/custom_middlewares.py | 31 ------- .../src/route_middleware.py | 29 ------- 5 files changed, 83 insertions(+), 166 deletions(-) delete mode 100644 examples/event_handler_rest/src/all_routes_middleware.py delete mode 100644 examples/event_handler_rest/src/custom_middlewares.py delete mode 100644 examples/event_handler_rest/src/route_middleware.py diff --git a/aws_lambda_powertools/event_handler/api_gateway.py b/aws_lambda_powertools/event_handler/api_gateway.py index 781bc3ef5b0..2163d7d762e 100644 --- a/aws_lambda_powertools/event_handler/api_gateway.py +++ b/aws_lambda_powertools/event_handler/api_gateway.py @@ -206,7 +206,7 @@ def __init__( cors: bool, compress: bool, cache_control: Optional[str], - middlewares: Optional[List[Callable[..., Any]]], + middlewares: Optional[List[Callable[..., Response]]], ): """ @@ -225,9 +225,8 @@ def __init__( Whether or not to enable gzip compression for this route cache_control: Optional[str] The cache control header value, example "max-age=3600" - middlewares: Optional[List[Callable[..., Any]]] - The list of route middlewares. These are called in the order they are - provided. + middlewares: Optional[List[Callable[..., Response]]] + The list of route middlewares to be called in order. """ self.method = method.upper() self.rule = rule @@ -238,9 +237,7 @@ def __init__( self.cache_control = cache_control self.middlewares = middlewares or [] - """ - _middleware_stack_built is used to ensure the middleware stack is only built once. - """ + # _middleware_stack_built is used to ensure the middleware stack is only built once. self._middleware_stack_built = False def __call__( @@ -258,7 +255,7 @@ def __call__( ---------- router_middlewares: List[Callable] The list of Router Middlewares (assigned to ALL routes) - app: Callable + app: "ApiGatewayResolver" The ApiGatewayResolver instance to pass into the middleware stack route_arguments: Dict[str, str] The route arguments to pass to the app function (extracted from the Api Gateway @@ -267,13 +264,11 @@ def __call__( Returns ------- Union[Dict, Tuple, Response] - Returns an API Response object in ALL cases, excepting when the original API route - handler is called which may also return a Dict or Tuple response. + API Response object in ALL cases, except when the original API route + handler is called which may also return a Dict, Tuple, or Response. """ - # Check self._middleware_stack_built to ensure the middleware stack is only built once. - # This will save CPU time when an API route is processed multiple times. - # + # Save CPU cycles by building middleware stack once if not self._middleware_stack_built: self._build_middleware_stack(router_middlewares=router_middlewares) @@ -312,14 +307,16 @@ def _build_middleware_stack(self, router_middlewares: List[Callable[..., Any]]) middleware handlers is applied in the order of being added to the handler. """ all_middlewares = router_middlewares + self.middlewares + logger.debug(f"Building middleware stack: {all_middlewares}") # IMPORTANT: # this must be the last middleware in the stack (tech debt for backward - # compatability purposes) + # compatibility purposes) # - # This adapter will call the registered API passing only the expected route arguments extracted from the path + # This adapter will: + # 1. 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]) + # 2. Adapt the response type of the route handler (Union[Dict, Tuple, Response]) # and normalise into a Response object so middleware will always have a constant signature all_middlewares.append(_registered_api_adapter) @@ -450,31 +447,42 @@ def route( def use(self, middlewares: List[Callable[..., Response]]) -> None: """ - Add a list of middlewares to the global router middleware list + Add one or more global middlewares that run before/after route specific middleware. - These middlewares will be called in insertion order and - before any middleware registered at the route level. + NOTE: Middlewares are called in insertion order. + + Parameters + ---------- + middlewares: List[Callable[..., Response]] + List of global middlewares to be used + + Examples + -------- - Example - ------- Add middlewares to be used for every request processed by the Router. - ``` - my_custom_middleware = new CustomMiddleware() + ```python + from aws_lambda_powertools import Logger + from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response + from aws_lambda_powertools.event_handler.middlewares import NextMiddleware - app.use([my_custom_middleware]) + logger = Logger() + app = APIGatewayRestResolver() - ``` + def log_request_response(app: APIGatewayRestResolver, next_middleware: NextMiddleware) -> Response: + logger.info("Incoming request", path=app.current_event.path, request=app.current_event.raw_event) - Parameters - ---------- - middlewares - List of middlewares to be used + result = next_middleware(app) + logger.info("Response received", response=result.__dict__) - Returns - ------- - None + return result + app.use(middlewares=[log_request_response]) + + def lambda_handler(event, context): + return app.resolve(event, context) + ``` """ self._router_middlewares = self._router_middlewares + middlewares @@ -646,14 +654,14 @@ def lambda_handler(event, context): def _push_processed_stack_frame(self, frame: str): """ Add Current Middleware to the Middleware Stack Frames - The stack frames will be used when excpetions are thrown and Powertools + The stack frames will be used when exceptions are thrown and Powertools debug is enabled by developers. """ self.processed_stack_frames.append(frame) def _reset_processed_stack(self): """Reset the Processed Stack Frames""" - self.processed_stack_frames = [] + self.processed_stack_frames.clear() def append_context(self, **additional_context): """Append key=value data as routing context""" @@ -832,6 +840,7 @@ def __init__( self._debug = self._has_debug(debug) self._strip_prefixes = strip_prefixes self.context: Dict = {} # early init as customers might add context before event resolution + self.processed_stack_frames = [] # Allow for a custom serializer or a concise json serialization self._serializer = serializer or partial(json.dumps, separators=(",", ":"), cls=Encoder) @@ -1005,8 +1014,7 @@ def _resolve(self) -> ResponseBuilder: if match_results: logger.debug("Found a registered route. Calling function") # Add matched Route reference into the Resolver context - self.append_context(_route=route) - self.append_context(_path=path) + self.append_context(_route=route, _path=path) return self._call_route(route, match_results.groupdict()) # pass fn args diff --git a/aws_lambda_powertools/event_handler/middlewares/base.py b/aws_lambda_powertools/event_handler/middlewares/base.py index ce22f736520..32a4486bb31 100644 --- a/aws_lambda_powertools/event_handler/middlewares/base.py +++ b/aws_lambda_powertools/event_handler/middlewares/base.py @@ -18,64 +18,64 @@ def __name__(self) -> str: # noqa A003 class BaseMiddlewareHandler(Generic[EventHandlerInstance], ABC): - """ - Base class for Middleware Handlers + """Base implementation for Middlewares to run code before and after in a chain. + 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 `next_middleware`. + The next middleware handler is represented by `next_middleware`, returning a Response object. + + Examples + -------- + **Correlation ID Middleware** ```python + import requests - # Place code here for actions BEFORE the next middleware handler is called - # or optionally raise an exception to short-circuit the middleware execution chain + from aws_lambda_powertools import Logger + from aws_lambda_powertools.event_handler import APIGatewayRestResolver, Response + from aws_lambda_powertools.event_handler.middlewares import BaseMiddlewareHandler, NextMiddleware - # Get the response from the NEXT middleware handler (optionally injecting custom - # arguments into the next_middleware call) - result: Response = next_middleware(app, my_custom_arg="handled") + app = APIGatewayRestResolver() + logger = Logger() - # Place code here for actions AFTER the next middleware handler is called - return result - ``` + class CorrelationIdMiddleware(BaseMiddlewareHandler): + def __init__(self, header: str): + super().__init__() + self.header = header - 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. + def handler(self, app: APIGatewayRestResolver, next_middleware: NextMiddleware) -> Response: + # BEFORE logic + request_id = app.current_event.request_context.request_id + correlation_id = app.current_event.get_header_value( + name=self.header, + default_value=request_id, + ) - for example: + # Call next middleware or route handler ('/todos') + response = next_middleware(app) - ```python + # AFTER logic + response.headers[self.header] = correlation_id - try: - 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 - result.body = {"message": "Failed validation"} - logger.exception(f"Failed validation when handling route: {app.current_event.path}") + return response - return result - ``` - 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 `next_middleware` - handler to get the response from the next middleware handler in the chain. + @app.get("/todos", middlewares=[CorrelationIdMiddleware(header="x-correlation-id")]) + def get_todos(): + todos: requests.Response = requests.get("https://jsonplaceholder.typicode.com/todos") + todos.raise_for_status() - for example: - If you wanted to ensure API callers cannot call a DELETE verb on your API (regardless of defined routes) - you could do so with the following middleware implementation. + # for brevity, we'll limit to the first 10 only + return {"todos": todos.json()[:10]} - ```python - # If invalid http_method is used - return a 405 error - # and return early to short-circuit the middleware execution chain - if app.current_event.http_method == "DELETE": - return Response(status_code=405, body={"message": "DELETE verb not allowed"}) + @logger.inject_lambda_context + def lambda_handler(event, context): + return app.resolve(event, context) - # Call the next middleware in the chain (needed for when condition above is valid) - return next_middleware(app) + ``` """ @@ -111,7 +111,7 @@ def __call__(self, app: EventHandlerInstance, next_middleware: NextMiddleware) - ---------- app: ApiGatewayResolver An instance of an Event Handler that implements ApiGatewayResolver - next_middleware: Callable[..., Any] + next_middleware: NextMiddleware The next middleware handler in the chain Returns diff --git a/examples/event_handler_rest/src/all_routes_middleware.py b/examples/event_handler_rest/src/all_routes_middleware.py deleted file mode 100644 index b1e3a6a7e5a..00000000000 --- a/examples/event_handler_rest/src/all_routes_middleware.py +++ /dev/null @@ -1,31 +0,0 @@ -import requests -from custom_middlewares import sanitise_exceptions, validate_correlation_id -from requests import Response - -from aws_lambda_powertools import Logger, Tracer -from aws_lambda_powertools.event_handler import APIGatewayRestResolver -from aws_lambda_powertools.logging import correlation_paths -from aws_lambda_powertools.utilities.typing import LambdaContext - -tracer = Tracer() -logger = Logger() -app = APIGatewayRestResolver() - -app.use(middlewares=[validate_correlation_id, sanitise_exceptions]) - - -@app.get("/todos") -@tracer.capture_method -def get_todos(): - todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos") - todos.raise_for_status() - - # for brevity, we'll limit to the first 10 only - return {"todos": todos.json()[:10]} - - -# You can continue to use other utilities just as before -@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST) -@tracer.capture_lambda_handler -def lambda_handler(event: dict, context: LambdaContext) -> dict: - return app.resolve(event, context) diff --git a/examples/event_handler_rest/src/custom_middlewares.py b/examples/event_handler_rest/src/custom_middlewares.py deleted file mode 100644 index 7f6e22f16a9..00000000000 --- a/examples/event_handler_rest/src/custom_middlewares.py +++ /dev/null @@ -1,31 +0,0 @@ -from aws_lambda_powertools import Logger -from aws_lambda_powertools.event_handler import ApiGatewayResolver, Response -from aws_lambda_powertools.event_handler.exceptions import BadRequestError, InternalServerError, ServiceError -from aws_lambda_powertools.event_handler.middlewares import NextMiddleware - -logger = Logger() - - -def validate_correlation_id(app: ApiGatewayResolver, next_middleware: NextMiddleware) -> 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 next_middleware(app) - - -def sanitise_exceptions(app: ApiGatewayResolver, next_middleware: NextMiddleware) -> Response: - try: - # Get the Result from the next middleware - result = next_middleware(app) - except Exception as err: - logger.exception(err) - # Raise a clean error for ALL unexpected exceptions (ServiceError based Exceptions are okay) - if not isinstance(err, ServiceError): - raise InternalServerError("An error occurred during processing, please contact your administrator") from err - - raise err - - # return the result when there are no exceptions - return result diff --git a/examples/event_handler_rest/src/route_middleware.py b/examples/event_handler_rest/src/route_middleware.py deleted file mode 100644 index a135971c164..00000000000 --- a/examples/event_handler_rest/src/route_middleware.py +++ /dev/null @@ -1,29 +0,0 @@ -import requests -from custom_middlewares import sanitise_exceptions, validate_correlation_id -from requests import Response - -from aws_lambda_powertools import Logger, Tracer -from aws_lambda_powertools.event_handler import APIGatewayRestResolver -from aws_lambda_powertools.logging import correlation_paths -from aws_lambda_powertools.utilities.typing import LambdaContext - -tracer = Tracer() -logger = Logger() -app = APIGatewayRestResolver() - - -@app.get("/todos", middlewares=[validate_correlation_id, sanitise_exceptions]) -@tracer.capture_method -def get_todos(): - todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos") - todos.raise_for_status() - - # for brevity, we'll limit to the first 10 only - return {"todos": todos.json()[:10]} - - -# You can continue to use other utilities just as before -@logger.inject_lambda_context(correlation_id_path=correlation_paths.API_GATEWAY_REST) -@tracer.capture_lambda_handler -def lambda_handler(event: dict, context: LambdaContext) -> dict: - return app.resolve(event, context) From 98948ecc4b9bab9c87f9ad89e43ca4284df1f6ad Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Thu, 7 Sep 2023 22:07:02 +0200 Subject: [PATCH 83/85] docs: leftover to highlight works for micro/mono fns --- docs/core/event_handler/api_gateway.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 9e47a8a0dfe..92b83096dba 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -10,6 +10,7 @@ Event handler for Amazon API Gateway REST and HTTP APIs, Application Loader Bala * Lightweight routing to reduce boilerplate for API Gateway REST/HTTP API, ALB and Lambda Function URLs. * Support for CORS, binary and Gzip compression, Decimals JSON encoding and bring your own JSON serializer * Built-in integration with [Event Source Data Classes utilities](../../utilities/data_classes.md){target="_blank"} for self-documented event schema +* Works with micro function (one or a few routes) and monolithic functions (all routes) ## Getting started From 20c344a5e5b8fb3e86a97cec68a23b92c214f9d0 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Thu, 7 Sep 2023 22:10:27 +0200 Subject: [PATCH 84/85] docs: fix highlighting after refactoring Signed-off-by: heitorlessa --- docs/core/event_handler/api_gateway.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/core/event_handler/api_gateway.md b/docs/core/event_handler/api_gateway.md index 92b83096dba..dd249ec6650 100644 --- a/docs/core/event_handler/api_gateway.md +++ b/docs/core/event_handler/api_gateway.md @@ -454,7 +454,7 @@ Event Handler **calls global middlewares first**, then middlewares defined at th === "middleware_global_middlewares_module.py" - ```python hl_lines="9" + ```python hl_lines="8" --8<-- "examples/event_handler_rest/src/middleware_global_middlewares_module.py" ``` From 4ed00769aeb9a8c281c2866d6c87c2a9357134f1 Mon Sep 17 00:00:00 2001 From: heitorlessa Date: Thu, 7 Sep 2023 22:16:20 +0200 Subject: [PATCH 85/85] chore: remove backup drawio file Signed-off-by: heitorlessa --- docs/diagram_src/.$api-middlewares.drawio.bkp | 1534 ----------------- 1 file changed, 1534 deletions(-) delete mode 100644 docs/diagram_src/.$api-middlewares.drawio.bkp diff --git a/docs/diagram_src/.$api-middlewares.drawio.bkp b/docs/diagram_src/.$api-middlewares.drawio.bkp deleted file mode 100644 index 5f82484fb87..00000000000 --- a/docs/diagram_src/.$api-middlewares.drawio.bkp +++ /dev/null @@ -1,1534 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

rgs}eknUO_R5&lj1%;tkkCG1i;a_qurs!A$(~A9 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 diff --git a/docs/media/short-circuit-exception-catch.png b/docs/media/short-circuit-exception-catch.png deleted file mode 100644 index cc39a4124c934852f1905f294b9f52c7554f16b0..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 210844 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⪙B6GTjv#1%hr zq_~0r?h|2%uBtdvBtMe;R=fp+UQBu16HF>$_^6^dQju&_c^nCM?J#UrK^)l#EQK1V zayU{{FD(xE#6_Qa=&n5`d!=ePvR<#Ncq^=gI8u7Vf{NhCZ|yQuMjR=fQu!_>h}x(m zam7y@iNTT52@jRUkx+gl`K@>h2ECXP;YjH;hhlJ~Pz7ZcyNG(-6hM5HM}N@4DHQ!R zA0wc&s~lz{OII0TFq`z|waQ^O2wN1ObTXI=MOt|*9vQ{l7$y5IxBz8El9mcY3uqbN zw|3MiA!Z|^N~9}G%7EEP6K}<4+;t3 zvzX}1y3L<;%j^xnQmK-Bb8`at52>;34W04UFIcaUnjkUQ~%M zSnNpWGC)rSo%>DY`Pk}BHpzuZu%L!Sl8AwZK|C`Le{*9I|ZhOQ6nXSukf3``Dto$f29-%6S6|NAK-?oOEAh1 z+exXQ1*1#8Oe&AZ@CBl+5Dk*kv7y)agNd<$30gD?#Tbfp2t* zREP%kOj3a(S$yDF6lcLu40GX74B$~n1Sip841yn*!vaSzSOWy4qUkE4b6}1&IB^9L zc{{2P9XKnj#!;CJe>QL#zQBnfzQYWuGiUfxnWpF)EC!8+JR8Xj%XR|xd9o+^SknB*&!7?` z1I?JufgTVS)B#XmsV)?G)kUldKrg6lfxd7;`Cy6+LDUIL@S#U?khg>v;lqWxCjPJ< z&?5pH%s>J&Ft{9FI**5_-nVNOFMt}1;1u6bE;G`M3*;X#k!%(oz~IxJgQ>pAd*NJa zFgS+m>JSv^$7BTCfOW`gff_k-cnm&+gR7bXHO4IP;qdvuR*=nPDl?yhTt!`EigbC> z7+mlWG~w5=k*Do}V~90@Dy&N)TM7OXeH!zQ2*rM_{^MqVAc~OG|Aqw{Dg#CnM6Jal zP>1TB$XjBdsHkQUi$x{9XwyEE4Nu!3aj+0eD7d^}DjNv2I1Ytlyd=ha$?u%d%n!x^ zi4{gL>5IVe1tQM_NBuZJ%>V>xK<9v4MO7A~h~RbzgBZwl^8=`eK61D;I(M-2iQo}n z>+l?(@aBc%%A_%8<2ycS*Y;JSt$5c)l7wf?TD;y+K=~bx;~OT{2>=(6GZb=xS7N{= zasUm&C|Ubx%{930s|4=bZRyWxc7myEb*I_UBYf$>0`DnkmxSZ&IF^=X*2Y14CLVs? zrha~I;an#{N>`ftf{_>iAp}h1&;URu5oqXk8qvrYHTg8uc^QKAkl=Wv*OMsVGO=yOmJI4@dAMbch%m-%s+Na9PpCYb79 zH%EgUa0c;%^ig*P4FML&hmB!P1+vkOAjI+a~4eB`-a-Z(t}H?)}TF z{_u&Bvh^P=Fa6>5AI(zzl$=nmAeRH|8m@#P)&#M5G9?Fg(ERX{BVEDJpyv=J@l@Y$ zNRG23nV?#P$vMFo9h-83$6!jhNmEX^QVjzMjQf{z?Dg~^MN2BjR>z$W-LjB@}q#Hx(r4_rBfmUh7-T|A$y&Y z;fah5n{N(E6i9qjsZ?SJ4Zc#LVF*U4zQ3qZLZ3vDfy54$a_SSxQm8jF)T>$Z`1l-^ zt{JYo!z1CRWF^p>aR?3m{nh6yzagn0gSpUGDv|A!M(|Q*^Q(Xd>QW{BkmA9gXhZi0 zK!4H&$lu2V$kayUg6gBcrfME;0`v#vN0Q%)w_wnVDUk(hy5?bg_n|=It33LH5x9z@ zKgF{Y>WvJ5pnT{L?kQt9ia~#91dYiYs~q~P&sQqmb}AqGLjq(3yS;VsMp5e{hEeBl)VD`xD8JB)=7J!JrpY9`uJZ*{rb|nj2PL z1rT5L(I51s;$4jI&;1E)q09`pBDDZz1eA8w!)y@0iur)SY-qMzg)v*b9!~KVPYE%b zbl&2-;6i55!c%Z}CS zm;MV#3yK@Y-$*%m%)E={nH@tg2K7UN`7qx%I|kR|qSz2y@5-?84KVZw^d*Jc`1(vR zv~?f{8p0l$?=N@77yvjY23tG{kICInA&-~}djyc~0Ogwae$B&$~`*Jpq6foL4Zw z35k3}rcnj#X7LXf}-{`?}Ntr$a==&ruUv_(% z@SND+IHpw(c^}z%`o8lErkw~0At!%>=IlnSnL8Q^WV3A@sTE$NtEy6>LuAU%2r zcis>oj6p@D2$|7fDQ4<7)iXAvLjo*v{L7EYkkNq{7aliOdb zNA?`>aSlHKDIc#p83l|e2?+&5g}@XZVRbqD6D;)Qu!1>kfCqTsk8tp8MevUgGPX!+ z{*ZWHQ7D@UCKG`*nCSup26Dic8q5#n3dV(@I?JX<@CSjhDc~(8Qy&gX5uXbl0p=N_ zu!w;bQ$o-U{!=r-Tune0R5O%JGfAkTLZ7bW^TIsM%ni*$d8R%_e)Mn~N?4?~1*HMS zl-tMsoEP>Vofn4dsG+5o^waVoz8_~^7_J+Hy$jNAP;PCLdzdA3GP2x`2s<`6PW-wc zx-s|OPw z93#HGpToNV^H@|k=?j%JFe8;F7@-enC^&>=R$YGABM5aDu_Darf-nm5%fZ2qJK4j> z$;Oeu4soNqlSu>@xbYx6D~0e-o)e;A16yv^G+&ISh9ttZhV##LA4h;pb>;YT*i@z+ z2blsZNJ9tG`TR(9XdE?^ Y~5ht+0als#+NWxl}ByS*rU3b1L8GKmk$p-|2xw)Ys zct_d^;}R4lJT{Y!yADlIV-wl9>(EH*`xDu6?=>Ov+o-dRCR;k?~$@7!o(<#30`~qyJl)E>$D*7Lql7@T#@_J}6 z=|-@%CsRdXYhe?rX!H1J>9&XleRNYyNo$D1Qi%|G44WWGlA5k5IVFt@BT!6O3U|t} zK`A`em_aEt#qtFP(k&H2DaQczdgf$&6{!`!`3Ok~Arf-i$i|Qi4m9tOG+df}d*cJ{ z=^#fX^U4Zj0rbCelDt_*q~X#CjiNBog$i^@;@$}q9!YM0gKd+cIZ)x0$96%Zi(#W; zO7|t^auEm=0^JXQek4 zskj{I``bb#u%AMQ?=}@nq28z-_=7-L%ux*ZlioB|HSkBQ&sQqmb}AwIlTNREAMg-< zS}K35K-_^AvZ?0yHC$^0^Pw0Z@_kHzOqFy<3gm*y=M~}B4~FQfivC3MBgt>YTQKOw zln4DGNhKt&gyExNGK<2~%1jd}lK3i*{zN0t#8~0`(O>g10!q8eVK$uEk{HZ}0v^o1 zp~_*l`aGQCEuQjWHrPpzv3TDH7f=H#={*#P7EsJafhFOnp%XPD$WSmP+zBR0Cmp_v z2_mL8A{SI2vq>ix6olF2^)Zm^l3Y@}-GRPGiIA3bBA{uJmI8^d`bZ0Uz~(?&if06r zb{UR9`L;$OJis_(4APRWsa7?lRj*%Cyv2j0R33{*mi9MNPQJ; z7HIo5WBc%se}r@0q~<8dH@rhML<)CioM^y@Xc@dq=>uHwmOnBy3oZcyAhik{6VeAR zMfMah8B)X=D%s>JT3~({wB$Qep zvKWEGgNf*dSSc~#Dzvs?txL0R%&T@Vn8P zTW1XG>Wqp_d&5^5^pXR_VgEY|= zD~ggR5MeZnMA=TJIR#Pl_z~8|9Dlb7R>9OjQSMLzY&$nN_r7lH*munx5|0`}ayOzx zPCbbmx#kWL2v%SW4~RDq)sO*ImQGJ7umMu07cEF;e2c-oPm#(PKX@VkN zJ%T>T2q+1nCoqgd|CC$y0z$8*IDA7R@B5`1|Ph_Bzg$u!ujD)A7y1%WbKMJ*XT@K1O&~F z;^5)W(V1imU<5+h0aP}PNvG)n#td!r~p zFovPQnQKim7ZvwP6|eo0h(;yGqTGij*^<-rMzMJ$2d(XFTFI%Ki#Gsq9NelRB(yQ ze0j}_yw(MUiA`u+zQ%7h>XdLJSdxeOV9~ay?C4xBA20cg*Ka)kSC#+@FHIiE0dF5B zpM~~B1tAA2>+*&=iXSg6kuWhNP))!P@UIvHO0odLh*V~O9mtT{Bauh9@JoYKa!@tC zg+y~~P3sK=SrQMlzFx5@lg2`zu>49UjzINGNqvM=>9sK&BMoCK*tP==oyx{mMCoj= z&|qL>y`E{A_^KlOw3Hc9d?5%-wxTSNHz6ac(ub^T(h4MenxPq4jJHux7r2BML54{S zGNnj40o+R0C6VhNCjHf31d5Xa_7Y_z)*=6uh>ti4(ngxwh%ZM9BtEKDDly6%pBQMK z6Qfk(y?^*bWsH%NwPW9mBcAc^uO37D?RX6;6f~#^>_@UhGV~DcgDH_7!ghXa9TjpX z7@78`Saop< z+zZ7hpsL~&kv#nuaSG0))+WU%iX^_u;}p1`j8Q5T#3_xyQq{#N4W?71OGmb(PDfNVX}f@FoH2$H}LNMh*WbaY{4iQxr*j)yFA6L_VbvSgNu(1xEQ8cOx*#Papj z%L2~L)j5oxoLBfJq-39ssH*{!-6Im<(uE zCTOsXf+q@;<;Jw5f`VTzhXV%VS?UsynV8}q!F#L-YjImSc8%a&8iVT3rLyXLm~0M@ zk_c=n3+*nbx8q&USNQyNWE&p#y}Q`jnEILq(=AM0BWxW5+&B~HGZ2G<{eIz<{_J}X z0IWks3N&ZmyFVi=faw&(59bDOOj*W0HfF)r(8$Rya7TD(P8V1%C;+%8MB5RtT~WB} zzNhbR>EMVAM2y@3>d0cCvxjI?c61>N8$Yf|$JuLlv;`SR zbe~2tauaRaAX!SRHDfXv!C-bW*(^MO!KXV1Qw7sh!a>Ru91GyHn5avl@`CBUNT$w@ z5kaSc_aquH723v+d&i2809CS$AD1?$-^Malr4vA+2oN6?H7O_}qv5qozlEx#lDe%Q zv-2NU8;E$j3wG?h5Gq!D#;e0>Ew?)mB?wc>r9RJWr_blTw(4Q?!8^iKsk z?eK4k@B6Yi(ep)S2_G5)di`-_~pk5))m&P{6ZLHF03RMx7P3m3j=$M^AkKQ64`+f6adKBwUNM` zqGAI@Ov%J|<_9RTkEeVHmA)utqfp z3*Z_fSfzwfKvhl4h~!BDc2$NUh4xl?U=10kOkE*+5OVG{D3bUp4`1MRI7X>dF#Xa9 zEQNX_L%oy`r!<&;k!~*diBqI}q{`wH13a7}EFNpb!2*Ifhr#w2*Q@=Aa|LiQ38c3I z{5aYrBH70z>KefqA|;$FU}wv>cX2SWHJI!eY#L!lcC`xjfy3)DzC|kj#g_Y{6C*HX zic(J%GbEsO1$B$6$)JK!PVbL$OxSA!!fx;}T+Wiv=eQMP1LR@a5 znS0gbrrf=vO<(rcJlvE{SYTC=!{rBX{5fnY(^6b{iY*`(bs=D$jO~dQ7Yp7Kcet=Y zm$smNNM4Zx{PhCdr9lP}ODIv4mhq*j&TOJ$m(ZwQG4-T?Q>m_hYnB2!I}4zgelgU#n5 zZjEB5OR)e)sG)ogSc5D;8iwlXU;Q(hzRsIU)zW@Lc?pVt42Y;$qM@~cF&fWc@Q(r9 zo5L1!N%n#?#zwe8$J3zmY(P>UFbA1-Gb}B5Zi^OuTi9Bdx)PR`?gA^%FDK z7fyVm|8~@h75!!w+*|w5WG4B;gSF&2d5LMiw{F*VWec322$Pm$muO9UV``Yv+GeiQ z&p5Tsxu?eUZK*E(^R8{HE+(^1FMrh<=d>$ZSav**_kAnpI&|KgTdcvR4Fq4eLAUeB zFy`4MU7e@a)>O9}HM3%v-F4%TCw={vX_l_@FWB^?`or^5|I|$b9X36Fn!l#_!I&BU z22}N>kI$J=u72WSP5*l@pU&^(bbQ4>*L)vUt~YvLdNYWgNT9ZA{cEdEea7&2#TmWW z+Pba!$%2BA6_=0COiZ@0^48F`UpRl!?|p-AU9w5gX*;L3y2q6bWzi?1=AJ3qZdcuM ztL2Kgv2(th+46KR=)j` zYQ5t9$Iz>l#=Dm6E=a$6xBIQ|%MZ@4ea>`wAADhUdW~J&A9_79>G?~1beB9{(CNX2 z;U{W-|3YqQ98$B*eNN@Q;^DVUTj{*>1B7|+SGD$-PD}Nws8-hYuiQ0=gDcliaIuchxg}|Pv&*i#x}>`}f6jS(wNpgp{qT_KUrY}M+!`?Dc-r_iXD^vJt7&S+ z*!A)6R5>I2(c{%Es;aAZetbG6^25{fe|KHFn)T+@FYl_}`))6dbk;x0FJ~rCo&Emt zFZxq+mhBtCKbJn1eQdDDs9O$ek95+!(JAz0)URvp3fKG<{^iu2YZ@8U&*!K2={~2l zFuju@>)zx271@9Jti5!xa=7_<2Q9bRFK@BOXH!)|zL`cse=UC_nAv zl-cY>ZjliWDF^OHeW{IZ6}j~24SP=ZktvHZlS!=kf$XIACQP4$UGIJ=PcGgu?ZCQ^ zJ$<}4jfq@RY;H|`y{_CXU`WxpRyyNau?LQeKl9qgvtQelb62<38XeLiHc=;wvfrsX z@JPjn(CCT!ZaIUV=_fNjy(+z#GAYfhL;2g!(P2+EhCe)Y>VMJi=+|!*hZXkHwmx1H z`Tla*qS9%RygwcXb{tuH#Xe`+u^EfX=tG`7yZrD>dC%c(HlAEo=RdWTWQ_0*bn?Zg}W@(8u)od-#Il^9tVTl9`8-OHMraJD~ats zbh~VI???#i_ShN!wjp`0dTzVyi}!2YK3R;y-ZLv-wY&BZToLtY*-iWV1{)(w1k9S(5XBii)#_*nQmqQCZ`Ol;$%<{a2hEcUSRXNnrw7hkmpC7!M@Ve)T zd0lA*@f~*G)^i`drmOw(o`&v2Q~ z&m6YygvGh3E`L}Tq*wGR+U&c%qVxOV6BciD{&egDFlq zDXnH!ympzo!+X2hl?@f{WAktAHhk?>T)zAE%GD#>2K79==RmsQ#}5T3u4YVoGJQTf z&*>bI{?Wo~RMArIrdQ?xTB9Q!ZcRiKRUJ{(j~kB-m}itU_gJplEwA$jx;gaoyR^Bc zmlJ=$`QyX5xnsV(07n`$NCg|_`vJLuz~g)G{4k* zIMH^t$Llq=wIko^EU+`YHI*6e%J zIr9FD6zV@QrlsUOUFY4Cr$*nlEGc|5IPS{XxPi5Mjd|YF%vk~}>upvKNjsWYQkW5SJs?KCEc?|Vhj{HsLcH&-doOY~==L|9^Vcs=F4!MD zLK)z-8Sj zy(hR2`#mYK|DM-Fe);{`g$%U?H(F0y*gfxdNcG%j8oNb`h@Rz-IC=MZn688_tuC!pNr==tS`w=x_ot;XMdduNp`abXrJDh zxc%C(3B$Ml(#78*jzJ#y6KXBrE7*1r%jE%RjTJ-~zbk7~poc zC3SeV*P92~L4Vy_9ds_>=3RPe?ZdZsmk&<-b5XV4s@PR_J5JwyymG{4>pKT20R>TS zdw*umCO+RW$n|LJvXZ$M_xc2f{`+n~_B*2S3yfVqC z^mS2~(?fEq%`n>yw!J<)*E_w?*7rt|diCL)NTaOXv7etCHYwC;z#d)Nb~P+}>&g4G|IO&ZEU&0dqax>@Yj>jUfK4`W{l->pnXvuM z%B};RkvPS}%C+w1Fm^8)Ik=)Aed^5P3z+=~WgTOa%dR`Pzq4H6NB#Kl-Ik%+(ag%c zb(9HLD|b%y*BTpkI&6iy?o#TdBa0hwEW1&9n;H0y?3p?J} z?mzZUyQx>kSRcQi^Q&#*@#X#g7oEz?CJl1in*8x_RYm2)FXN)KHs1K)eDOy2M3=3e zwpl|gH>D>8AGMjMzVi8#RWCGLNCEFRniy`F?Ps$$?FD)JquK?(?Qs6UyR>O+ukK^2 zEzV_+N-6p4{x<4|&a*>HHoyKWYsZ~y<|?uGTy8THW)- zwZl=vx7n@!J4^lLv*iy%YO31Wtsm7tdHPHJIBvl;U+W=X+PQzy_FDA#Y~1qW$9{Vh z{kC$)ivBO(j!*V(J;w$puP0F6VJ~|aE(6M|0hHH#0L6ss=bm^}Z++I5nYX8%Vjqrp zF)JpxZ`&bs^}!2Hz2kCoX`vso%CpY?`RsSgdn@zyAIshEQ*IPEpXE)QH8W|;}w;w;{?!JO?d%QlRf6NZpuf4Kue3wsMJD#!b zaLPY4@Ry!#mL9pb+abK@^|IsLPZ-ZGZ9it;r$w(nv>RK!`*@oPYSeAXCN`VYUaU{m zo^U_NZTCx;t&aW{9Tyyace%#4V`%=yu}s%bx9Nu#*;N6r)NAd#;ogTVCT1@4d9$x( zm|23!Jnw=B_pjzyUUxj>ZlSaG)%bXg5q_69{=q!AvM~6{p6X-*JK?qaOQXG3&xWnl z$~re^{lcNQ$1k$l>ZR6^W;@3t&3fP7m2K0yP<0;m@poI5TfR8u5|Mp;&DrUT9CqJH zx-%he-rF!1x9XVs$QR*Hf2X`F+IM1S;Np&bwk2%2*w#XOM30C4O+2+jOEi$ zrbd0zF2`D*@h)B7o1N|Pe)Xt*7gr71*Se2doA5Ue{4~0~>ZxNk{T$bH=%Q^$%Cv}X zFKqX${jgIrG?p`YcA@=jhr@5~#PDDIz4%c)adws?k9(x-65)Ay=ToOPRGvGslRPFq zXt_nzaOlgP`Q3dh0=4kJBBPAk-K~QzKY(j9gmv_QaQ+ha*VAi58ol`LusPOYq#{ z<4I}T(V>LUDf21oSWbsEhoih#bf0(d#os$hFDK4C;L$hF;kSQ#E;~_M({AcazSX($ zPg$4SPAFM9<1qW-j$hMAwxxIW9+)w+l95dcd>XUo%F21ODlSFd@Ulwvo*Din#xQ-v zj+x79W@rY^{$rJ+>-hV3J1_@Y)MSK5kGSY&vE@(igO1kJO~)c8PdvHs!t>A`JB^kl zy!0vkH#X2o*OE)n%zwH3)Q*~Ity5WE#}Na5(~GfoQ2s*CB{{KgiguqkYUQ@^Agj-+ ztFCu!=HGcY-a|Wjk8%74t&K-pmwUQB*W_I85P#-f!HSs`#jgr^9>@8smvr*=tlXb^ z;aaw@QCFjLOS(K89_u0j`{Tf!gZ<;$T(`w;)fPU&O$9>ns*d5xoVC#yU|fn>YQg%2v0jha`Qbg88X>Vkk^j>V$$awH zRAc@-#~nrSmu!bd9i3&FURL$`aL<)2jk1j^NxpZPMS{Qmxx%NIH8jo9b5#X1Lny7k(zX!3!u z&}BV(=`fQQoqFeUttK)+J33^!-SiVhS^u+M(c8UxcHG8MJKVBzD?{JSrQSKnXcu^6 z&*CdnM-JIy?J;4#WA&UDOSH5vWwEcfTHeFRv2v)_QSIJiXQ&T5u_X0)kIJs5*Ei5^ z*4{mN@^|p4J@>p{8JiYf-|&1GA!*Uq5`dTc4;64+eD3 zAD#Bl=lP)bJ0efNxkNrQCHi06(l^%*9lpE7kbc)?SAg+v zz5AaR2roO^w!Wl&;m9?O{ekyMq0jG9N(+;6*XVuOxh`WueBR5_^8A~(k}@pfO7b3_ z+4T9Z8;>F?JI%bhH`GzxELBsZ+ksqajeXqRgWg+%dOwQR=Wa4Pn`BN_+da18+>bCzn%GXBTJEj)q*{-1V0-zrviZXC@ud)EM6V-MTgV zFU0j4dbVi#f}J;f|1i;Mo34|3sQUGdemdh=vud_@e;?vReyV@1gEH zdcP{^?OVpOb2?FauXp<0gN_xMhfK4KH7%1~EN!8k7@`)n&WO>L$IV|{zWz~3taH}O z3(NYXWfg0UoMASRJtf<4tM}-_1oE860nxi1x2-r)Tee<($g9KmH0N;n2X};&#a{ET zp7wfl=T&#YUnaf1n$9bje);wNeZQ?U4B9itKZfTQe`eUT?u+-9l>B3~`LO!EZOJKW zdkO7;wRub3ZVOI98Y<#LVBYzeM?ob@)R zO~`L6-YnX4C0@Jj{N=9HXI(9xX=z4x>ScN0yy-)Y!DSnbXICWOJ>S1obVhKwiI3eC z`cs=1kDtzGom!dbM;p1Ri!a4Jz{Er=R_nr)S$@ecGv4lQGpsD!Y)OnISBDpHt|rGj zGhinxe+79AX)n>(emzO!`k$BDoUgf*{bc-&DFlw%`B}aATbBt$Yg6rCkAELKZ2~|8 zy$~q>q+Qm+);4|B+az0dEDUGc?FwT)+*vl%hUiACne(C3s==PUGdZJ2#h=L;a%R*H zqoX$t%^XPCLb2%h;gRcu-29NFXWE>LhhN{>Hm7S+F17vmr|J9^>|^GgSLMwe7L{bQ zgxhLy%&*$LZHQbaP3?tK5>Jd9<8^vOByS+c^D-yyoc-BOg$vlP#;!S>Pbz+UEA;?t z=%W7dPXLnNF{zyF)${WFSd%Y{Lgq#K6vxER_TOl7%jvD{#4RfByqTy>wl zbl>Z_tD+`%1ys=+x|iC{NKBKMy?_{ z|9a?Y-`4%V92h^Bu%vkV&7rp!8^`;6$l~1GX_-LY&fK{qaQ7rNfw2nJ>3hlEMn4Q4rF#Pa~ohw z{B*x_k4u$1rW{hwq~$Fn`?m^yT}oO1uJje}Z1RTnyzRyxAM~sZaVv@GJ$i9|LHh%_ zlMV!K>})b;ng6AahkD)!+;?@!9__@{;ZA<`DIFruADL`%_T7gCtf$Lk($|vw7shlx zA2`-pJ6hiwM3dK}+^5iUU)s)Xy~lK}b~L5tq#MXZTBx_28Si_#WPf1xiD3noHy)cC zxM;t_eGk&xWx4&l%mZ)i>Rr0CSJ|zZ7Y%G3yX{bCuX7(g%k99JD;r1mnLn2}ukFN= zmA2W$w%vSp79GzW(tfbjpR)_c@E%{HmXGud8@9W@PVBaSPjL3NOg0G3N$;eweVKEj zdtPW?jZvvKW;v(KKc@26I@zow%sX?hWt>G^?33-&D=uYc&A6n|-I}$g-SUd40}r9UgS~l=8mQe#)uNCa-vtVovroThPTikMXo}ar*wx=WLu9 zdo0@QKDD^7`lh$bMhzyljQ?DAzAQAAt!5h6XY{;CUbk^s>uf?mN^DNK#iN~WsY^z< zo-^L-UTSoryJ3w^p6=7-2eLJXE^j|CvHvY@<`rC`w zE6$?h)VLAa(c8c5J@TPC_bABjYOiQv8JFvOd1QQxwjOgqqNE?^Z(Z}8Rlk<^Fi*O$ z^j$yQs7=~|nZ?U;sU;m&J}vMhEws}KjOnpBm)iTrTHf?zweESh%rs0AbZqz7vsY@D zFAhCRoBPEx_mAHOC+wW2&U|z4_yqdDYi#E;X9wKNSj(EZ%Hum-EQxjdbrn?7d9oD6rW`m&rrMYPP;H>2AD-p89Vb?&h-54 zy%r^qW377?b~ihBt^b9q+a_Hlg$^#u^2qYFiDym7w0?M8a~S7AO|O)sJ=13%&^IA} ztZX}CEAimtsM>`iMw>0MTVg)cq4(HH`v+N`UHa$co~fp(AFCcMs9bQY!_Nn<`<-XrOga>FyhCW{f?+A%2j(maOs!@Gd1&xv#+#RIvYFQ9KpO@-?x5*H z-Rx+czgOpUe|9#tB0KEtt*#*UT0_cP^?2D;Kb?wI3$uUu@P~64HCC%aqiTV5#V+Th zWvho3SL+T-Iv;i;jhAwElTOp^}ZPjI<; zCyu%yx35>*l7+ty&SZ@nFxBaJ={?h4`-fPb?PPl?(5{x={b)&>_{Tu%uFUo+sR{n` z^OmVk*uYD5HOtzXyduZo?(`fJN^5oBG97F6{L)Umcvpjo>wnugqJRFQrzLIF)@wbb zg)CkW(}8v)h2oU-PHk|K#&z@#Rxf{LlV*6FAV{2dAFO95S)2T(fBMrR|l*Gd7K{ z?OxbB)bNp(&$&2O{+1G8$iY{<589JEIeQl6Ea%D+Eymy5_OmvIRIDwwk2jBF8oJFW zd~TQdWm?ao>FrJJvtskYh=a>UC62OJ_q8Ir8IPEpw{~A>r8d;moce10UVSSlwh<`hcP+H@F`s>B+ej+grCa2{m65zuEq-_LsbE zH*H=qHXQWPN)Pbf_x{hj9@*2w5;yR#Wrp&~hk{7nM7!+j{@Gckha$T!s&P`^ra!g& zs^84rw&Vt`%2@K3WykC_leX`fQN7Fj>R^Hu(c#vzoBHQ3cC=1(F-bGGe@WnO80MLE zGRz=7b(DUlt5w#lDaKK1gF;Js(Y+D|2sYB*3KCh}K*?R{)&@X;<`${g| zciR3(xwn#S@&*sNIpns}8eoexi*n9hxfZ78J96nPw%y|UdR)zd=&Q$ztWGS~Ia$Ur z$?~*t=0$B(GgrY7g3WtWxLhnD1; z4d#A4{fzbUW?1)63pa0B6f+PwKz6*|OgG9qPC0#~)}225zvorW{8Z_6BV_4mv&WVX z{>`6LvFX?X^*iel$1lmy*}CXXcQ3U|iEf`(8$WY4T;@x?Fi~?kVDHXPtA{&x*EZ-* zzq+z^NXs2WQ{c5zwbi(Ay(hz{pX{(f7*wzP0PgQHy>23r-{U z`P{$)E!WpaqrSA<<+g`9Va$-cxgbNb!@h{XjmSNATEk=+E$7+IKd9xd$0u0Fy>-8E zbbP$#KQ~iTULWkUwnf2OBXeE5)jlZ;udRMPWasr++v1L_er=T5(T(9!Nsv!=WR#D+3#%g_OAhvjwQ4$ z8B1nG>Dun$0y)@$gprR?YjoczXG+L#6)K+jk%Ncqw>$ zZa>!KBedSXckOs_xNhtWFN2^Co}L3N-P%;VxSgM5;Zp0?HP_i?v~P6#o;%{MQh2LV z7Ug~Hu$xsq^3vACzl_%%-uCKl^@5Kx2kCN-->dSg)-K8#1$2EskJ9^e`{_s)^3iHw zc_Pw^?gXg!ofo4Xti!dL`b=jfci66B<&-64?dT~(ttXB*8x4S0cI1-*J{MwB2Mn+x z_USjY$il*akPuW`e%m{u#wKgUw%?O3k%s|J&C86smwYvMvs+orHoNk9dYr{E1G#4N zvWIzPdmMYQ#wTUzX^&lcDcw2CIuwEQ!Pbd?xs|4nwtRfL#yeiyk{cTJV*Rx>Nb22d zdWjwt6ulAr_R=T+`c;NZQFQri}vqNTs!U+b?@|( zfetqqBdx}C_%x-%`M_?B?NyIMJ1n2H8P)N$C|e;*u+dVkBy)@79D{=P$lwKne6=B&^ibLrfe zfzh*WWn6o%NjS3as9oz#59b`)!aW1B$4;{yN**K_o$9<9kziL>r<6A2*F}7%hx34N zxhL(ddPtkFmr}Mv(`Q@pK42cq+>U6T1M0xMWHvV@=1c7-?+pK#elzk8C3JC3NbT`D z{w3XORrbPx+~mW9ZBovD$-Jq(=kX<5tHsCOUm~Ye`Of(;eEyxjaF{ogby5(5c zRtbA%B;0gx(s}SD=kve^6KXfTE({nGb{9x#Bv-$D!mIIbVoL@m6qO!+_|fN%jhD_9 z`po71!G4ziV&D|i+IQ3{)OfY6KjXs(|AN&X0bSG#OJ@3>Js#OEt;%lJs=idS@=*ys zqaM=FJz012rHghzc*v@c%THV`JJ9C*wVJKJ1nsMN;0ewa(T04d8rgn!2RnhqtJ%J( zAhyvSf3h?A)xe7LXKhM1g8cAB3bjjrVp?S0vHg0dYFQa25B|A%cxJ}Jm89S`Z8zq8 z&hq|!SmO5TcK*?tmnNob z-@{*d_%yfmpR2m&yX`dH*>ByQhZlB?`>4zL++oZ4s$=a>)ALtWTO?)FuqXH800>jnU~czdOfsA4Q#dY|?MQiqq~smTt`CrFJ?=`=txTU$P!=GMyA$(H9d<;fWC(Slo-i{`KGapBorPIN*< zFXJQLF>~^_O|uxsJKiNWD0`YkYEAZn)-8BD-H!ckwY)o9^4cClTbO<7y}rZp)h5p#=2eC~U2^l3kJrL^%e`(d zs(O<@c%*jg*tr89uh@TV@WJOv?`LMGv}vC?TW`fu?uhi7h*UWYG|C3)@!Q29@3)_F$!1T_2bE4^y0r|uR24tS{WvqG^+_FzTVH z)`*BfXZNQ))4$ka+5_$%!(7Jo(j7Xp`pgIt(O^`WRTgdM3tDU}98?k@& z(|4eZ#WAnTqO@U!NwEu4wHM6J>$$SOdl;qo$j9pi#u4vUvTTnQo?jibvG~zHJs2}< zTUD>51o<8Ev5dR^`9+yS;3rp)fwf0wjD4|Gr(c(O6B7>g9ueU&+uO{yhuddui>H^@ zTc;mcX?tjBXzr${>b-siYdd_o_u2ZKnMIMBTTlAdAp2!x zoUi#GBd#8j?xi7q4jJ02}-iWjK<7b1r8u9*%M`qhj zwc7AJZ+*LKsTUjzhN-n)&RQJzW?<325{v$^gR48PUtzSye;sp?TD(Qp{mA*LHJ?{L z&pT0Bdv1%l^@iG>k9Q2ea(=;I*$2h|&$t6r$n-Creew@%$rs4Ce9DW|xqs_9+dOW} zbEmMF*0UCaGOd&l-H~QUT@CuvxpzzZD`)zb+o<#sIeg=z@CLxkR!+BxSs=X4L}KzpOd<+Qfoi8^V^c@@HpIb%NgB;Imv=I`X;n>EQz5#%IPI8 zrHg0>2=L(X;H*U9XZwzeU$9@qB=F)9Qe*e)uYym^Jq+sfidnsVXNteAZ$cYzQk|85jOKxKjnS$6SN+9TVKEmRYcnpjt>DnO zRlwh=rBy}pFf7(@Y2tZq*3l&!_ME=%y65HaEU-fiZngy|92|t@ndr453I|b&iby*b zP@C|p^ignR)_g?BgZqyJn;=;Fp|9f?5OIzI@@jxnRxRvV*j9Y6qFd+-c(V*6=a@HA z0He+fyq9Y)5@qZQ$CByov44wRSG5MG98+u+HeWzJ!HwN>*nH~Ar&B|w_8uPpiF3LK z%G;C65lvGYup1~5{9N_`Jeo)qRA| z=ubEzG5QI6qJ1j98#hITR0Y>lO0Mz~)9P}OaLJM7fDeba&@9F0c;to9IB9HQPvo*9G{7}PXyjZPlOU=b z9oHJUt`-LCgy*mr48CU4k`$xLuC3PW-BiAMuZ8DW(w_x?&?_q{dXj7Z9i3aX)Y$yI z_u0bkNp5jtcQ4giHuhoM*v}94|B6U>JR;%OUcNd|)Hb(o{>23@hr{n&?wXL&+p(cGPoFzHQ>@;eq5~gLA#Zf&OatgYjPb{%-uwJ zvZChSHvf2fjjqkQm#wyEfonqA-!C)Pr>9>jxO_i!W@yRtux)!*0>y6y?$hIBTju;q zjYoY=3!+P`=gesR@1E{aCEKmX72GX-Zyj%5aKi0y){Gj@jeUxcNPHp^iNELuKz^Ix zm7AXvL>E|gz5ix^R(Vy>yQ(=E9rahNvDtTqos~6WtWo&w*Ei!+isCcP06E)%YEo*; zff;QdILuwpdUT(JKGiSOt{(8KiBIX>a&*vn_~(oFsT6=@DS(+7e|p~;GQ9su)A^gu z8jBAXjoRSVcs9#@r}) z-$PA8XSsJ@{=%&o!v=(q~D#UeF(U^ZCHfBj&IUn>mLl`vqDDPpK^d|ju-SbVu?r1 zSH^lrqr{pVP?ITdZ;)i(F*(xs)Hrjk4W`6Op(Y3S4-M=ZyTacHiyka0$%k(9W0Mc2 zFc0M4v&3jS=N8ya6susa59z-U%T+qWuHKu;^1Jyap{d93j&L6pzjcOZima3u1SUt@yq`mJpOVZ^$G>oKN_#vd)dKXV4+>tU^yL z27}ALvMdAIUK<*d)5d-J6%M)WuSbcRI8<-7D`ACP1u{3e+SUJz(!3*o7!cZV!nJ!=^#rO#pVcW^xr0B^IQZ>Q*$IV=LboMtm=l&`%=1;~uPs z1q6daIe0hix?RJQIB*zA+uLnV3Q(GD?e{P!uCWnr5CBQ<3y#3coU7Jq{jY!`X?fPQ zK6Tw;0QmN}fGpCr;D22t38w?CEOmsQx&4$LE4n3K?un%ohg!}y^9Z{B3P_)IZ(F!! z1B~Qg+#coS$}_lxEn?RCUh+y|V0Q7W z?9pwnaJ(-6@|;Ys$*Cyo(L!z=s`)otlLj{*<@k>1GRPS!vHwVxlxn-q8$_5&*~|Mr z<8>k?-4Wq))2RE3^`xfCf3eyUjrd-U?G{Y^^3ezWS7h(mbe_j|43zb3f{dV09@x#* zx8uDhHr#H8ytdKjk>&+8y{CH%J#doYI6e*8R3zEK^!4p-HYoMJtzTm9Xx#3NXP4AB zi%+vWFU?b{yUUIbFzJ-5=~7<7=IO=tZsuRaI_pX0X)b&Jo|G$k1VQU zf}4Rp(l0_$chYnr7I}ZM?VehRHa>l1Qde0bvIOYLD7Y+LbrBsNdyLCZn&J^SN-lbfK6g=)(t44btKf5#=4YLM#r~*q#>fvOo4-6RzAE)+w4N z0(8}KGe|g)WEc%z5nB~RWn@soIrq8B88ebGWBFo|zi?L7e`fx)n0ZIMF_qs`zt-Y^ zD-qZz#q1>cvhm5y-6f_QAcF{TCDmA3QU0+4KrX-&&+ZtF;O`wnRqM`JIpfNEPF8KZ zfKonVHx(DJbutiP)Jp6hCFXv6{j>g9$Y=gD1w%|m6p)u>TkP4f{Mz~ctHN<(5xYCX z0P;J!p@O7i|1M)$_yi-?1XYXoP%)E1Igx>|f6Qp^^+?U>olu${xm#MR{gE<#i*e)L zw~yr0fy)h^zxJ9saa;eMbdPnC4V~Hv@-2#0vp7pJ5~J_t8uKNU;>_4o`Rmk_jV91F zrBlA4C^!Ee4w&OBLt?itb6eE%U)=zlIJ!au#4_w)0J z)fZW^#P>C;OVV0=x>=puxjlTuv;x>b=D=YzXEOlbQujiSBtjxqZN5lZdS72ud13Tv zs5>tm4h<*T6D0wSj`2>XyJ8@E&_@tH3Su5*_za{ko2TU$;`Fy_xdn~U zfkBt~?99yb%7M|Tlix1B3VR+PDw0;ckg4gLwdws@X1nF)`Xds$m3OR-uAAd8U|=^; z!#bAF_VVu45RJ^>_Ee=~WZx1@Wi$3gj@htV65KM$C)*1laKhuU=n8iEr!cc_!xw3( zk!d{HCVXw2ud8CN*Wt{xg{M>7`u`qJog{<4TSVchAYYt#NmlOl9+ zVIgk8E`n^=XSwVVNH6W-We#a$C$G+@fCi*|8V4vx9A+}d?Uw}ilt{9bi$S41IIGHP zIv-GQvsTfo3lRl;He~ZAL(Ewj+tLJfV!`&yFJh0)5LW4Zu@gDyOZIbC|B8*0iNfl0 z!x`s|FqDe2eZ@j_xldxZkC zxYjHgD$@%aFZ{+fP$K%SbKTGk#=!_3-QI!}co~h@AKRkmY}BHMQD9j{Kd?177`#(A>4&=Lz5HUcjd1{8uIuMUz7$6-dG zlZt?z?Pp`gi~8!AeSe1yu)@$pMx~|w%JaW&`p}mKnhE9e? z$%Q-*l&_kol5*`=Dvm*cq1S&lx&of+FIUn7u!;iUVZT|H>LrM@uSLbjt&&tSUwYDO z!Kt>P802l?ri}YQNNHOPTj`OQzw%V6b$Euyp{?+ccD81xbxlzh)_-hRwPkUi4uFIh z2OYF{C+lR;Etu)muYb6*AXqZjMU_y*-94wn?yksKEkayU6nD{qAP@fFK`{ z1*f=@o>*A!KVCG*phW%*uZB5r910-ufV$_hJ%*A0@@xB?z+su^ibntA0+8V8RA1om z+0C_%^>R7#NyE8PQY44vn zIEc+%tPphjh!~{Dm>kpORvc~rM2AO^%pjS4Zh``#@2E39&ze6a0%QJdG5oP8Wa5JW zelZNM=LsKLhLZtuQ1>u)&||YMen@NM*>u z@?UQ!sRi8_DPWDj=ZJvINx*J0=x4C5W+OU3e!RWle#cZsd4I;QbV=p+_qh45tB8iq zDT-L^d3xFpAfXcWI-1(5>x`wuTw#dOU@Se_p6J=S?7)x|1*`J-gY!Rq+@XK=Gm7yN zm`vw?A|JJEPJq=-3|Co-HX&(M$dD9~@OTm70GaTKt>Ei1@lgOAfrV&Lb3tWT;{K_| z{OT7cxPGts3a=~MI%irf_9KqgJ?j-NFf>95*UW{0FakWOeK%;7Uch|GHED3{pH&7zN&8@OT^cAn@^TPip-0t$Lp7mUD?H122tHr*urR zeudwCtI51jz?7A)B$;VKfO`w)^8fkWsTAT(S5v-D?e8!Y>NN|}xLyV;UL(1xWSjGh zm5f3dFFKSw-on4RUXdtdaw~nkh}hpN3S7UPQQ@C4ID$;$6bp{mVPW6Rj36Tys*;$g zd_DYCH8yN)OO+RwF}AD9dXm%i04-yaP-sOI?j_19|F^G=#ycAFS1thj%i{?=G4K0) zprXd2iC<&)Ge)*a^i?9DAlS^-X|K}PxxmVmkE7EaG2wfFU&lADWKw8I7X$(#IBExX zCfXu5e`Ff~THK|EM`$V+dnIYaxZ%a>y*GPCqI5+nKkdBv#{WzThy!($$ z071=r&cpwG>Yts!fLuL*eMeVhtbeCN4;bKKO0sAu;J~9Q`VN zb%_K=5v5SxS5EU@mOu15{zXyvsLp(F`&_GWpA`C+x>_pI+}6R!e;@Iaj568NWxDX7 zX;Dxp0og()5TNQ?Wt^MH<<e&Ap zs&NE#YHY)67X12Gi&$_OVx@pyY-xQx^!aMR(#+5#e)bxBN)`YR@^tbU?iwPqjF>>$=4U)tTK#qYZz!d|V7U+<|Qu+L401r=1-$cl6+475QJlXjnUfcEU8_HK}g{oIW z8Lbhk1^dTgWrHcfp6NE)=j$2XA4HssbvI4v=M~|*@7D33g4*xwzA82}3 z`^A*)rq;$G60~(67%zcf{6zu22JfiAT}NmXH1Knt#ix*;CsQrG>oT!*#f&dch0>u z%u;jYww@(rpZmb*K^;Dg83yWDBQjwnG$XkcOBzk5;ceEI0?GDB)|H{D_ROb(!%Uq`QFDa9ya z()d4L;1UsSRFZQXDgIu3N&j{68BYJezZZ%@8Jse{Sv%J9ij|Pobu(7&QOu01l}Tq_ zrsazgPC%rw#TEFDFY0}QhPuYy4hjI6{HCIhE61Q{XQcrX{X~w4Vr?dV!`iK=t%Z_IGl4hyctt zh?M5s8$);r&-ssi`apgv)}8T>R|MJL%8S+#(}uyoxJyJ zg!tS3>e!|Re>Ghh0BV&dNr?KxmP2ODP2TNGV)XWoG+A@FdPd+ek5wmv0xd6z%==`o zy~+FZ1(+#tT=#$`p+}hM(S|N$Flg%lu$>X`LD<`3Lbo{TCZ6&Ta zRGDasx2lXllC|mjXc}f>jpH%3VLD!lC|^=L_Y?#PX@c)ySAE`IA&TfN_TbQe+k56r zOuRCLp13ur#P@J0 zqv?g-CSP9UshDhLwLO1dukl;LPY~mb#BARlUI1i@9IUbgGmkP->tArg$5?zj0P=rM z+ch)LDS2>6IMl5xm+)EdW8Y@Qz0lJ|K+OY4S?=AK<-Vi>%h9Z$dZn3k23sqe>B<3m zN_m4gvpu?wjrd(T^UWUvo@KKS!yvFy6)$!BH(xdNafAwmA<8)GBEnuU4ueLoH8=C! zZ*f6aR6vsEQcL6Z_~wWv9)=tS84Zd?jRDY>;IA6;=1iiVUPywm13jKEo;Lvr2r~)h{sc^bwnG zF&a<_y#+aXomo$0k$mg#xASm{Yx%s(e%3aGwBx!cuXl6F)P1c*SaQ!W76HObG;`3p6hLv~bIar@{z3huB;oE$R4wF$#@C)Wsf$F0$0( zM&g-%6Gp@IOk(0uq~_f*t5?~OO|#x5hThHS&WlV}i`f`O+0;kqGd1TZaL|6B$<5I9 z6Lh^$Yt)i^+>Q)wAzOO=pl3Y3>X z-G2H)DkiPYDQ}L1J*BEG@ESSjr$+TBy?Pg7Fi)lCT2y&{E{=>U!SZM;-W1j`zatCt zLrL0Kz1f=ers6GJ2qP0HH$C5^x7v!jqV_s~J_M~S-EcA|vAVtX^T;wY*b|$%Mh#on zc$!Hb+p)VhHwc4NrTU3Hx&&y%yjWG%WAHt%n+#+-#+BTSN#vg>pnKPz533E*-b`^W zXX~sLGwmCrvk6S2dixoWv3%DWSut_j+0t^!67p-T9;+Wla7ZAAQh3LAIOuqoAcM|q zBLHZxwxuwFtl)nSxdXsR=8i^@R?u|C8ns`ehvjT04~u4g*dHTtG6hAI=J+>PXIlNh z6rpjQraQ1wP#j?1Gd~6}hKhLW-jA>SffZ|7kj2|jnuuY_6gC_1Q9^e(}R%_*s$3 zlQ9C)Ry{#cUX)queBFM|@=MIUvh*X9{O&SNYz8c#@>H|paP#nr^WVC`zw$YyTkez% z_`ZiPvrPosAMgI|adCicKG7JFT#{kh-^C0`Er0TZejsR9_kc?G;D=>`JDZ#S$H;WC zfv%0`q5Eg&zJ+3ZNFk!%LXLV5GH*|CAV+rC+k>W{>`ED#%J0n?lU^;=a(85; z_<6(%K*sog`6CWxh-k8k^l36hk_l846b*rPYG9fk6Kh;Do6cKuF`KsQ%Tvx*KU~y` zG>Ge*)+NUycmONc4~=L})Ar+hy(j4!=#R6{@+}^G%@{+8b0eRja@*Eo*-Ohsk-|`p zf7JwE;c~5e8U8m9->J%PYl=v|%5GepFDHS{t&VzJuFuc^FsmLNKtwC+7!A5gF8Q=F z-7m9$82Q$N6PFsRg!8q(X=iMbWYHi|T>}Z|l;?#|}^d`+Zg&Y~ARG>PjoSD+`XWl6!e^nYLk<6z8^0Gu1$ZLqEzZ-K?fQ;+Y=&onrXZnZ`mvua$%!&E+YGpUo}inuLMG~g2nZa3oEQt0t|FqnSWe?#7!#9ULWj=|e!K&KUO8fIffHybrg{JUZe*?E1uNrpE9*%~&WNch&N zJ^c9e0libB*ENl0mrVLX*_k9}XBYw32gpdx5rfYMI@Wsofr8D%A{K!Kj!=n~V)X(! zVUL@27Co8*SGPwyH~4RL}UI;Cf!lQ3edRG+b6FE;nSK5 zF3bv^_x_+SeceG&mC}hDLKDiESFQwSzcRF@k&#dsDPf>{5b*kby0*RI%6a;MJ!(6R zjM3h%D|Yfd^Rq04i#13>Bcjsv4fzC8RBK)Y^3rY3qwm5$knlxc2a#xd8yy68*Iu0( zr$S);VhA79FG*sq>M2lT+@E!!?Y!X9<)}1BCg~dG2F1Qw-_)~*jPlCIUGWPOnZ8T+ zA!ka|l{(2ft2g_SFoO7Oi}Ku08-AsNqfKFNCvLk?4n^bB6N6yujy0iP_bMRqCORy! zd|&pFhf0grZe!3~T{<9xy=`ZQwX+gU2vRY3w&%)F0j#b029Q!RvK`{Z&-^Csl6+h) zi`l0dE@fPH=5WDis;HRsnQYsF7#8N{vV@hnI#hmg2ek6`Y{QH|%lRy3IG+PBkd`V0 ztKNi@vFq|_w)d7&)0TOTYAB?OV#769lYQ01%6Ncj@VQSA;MG|vPlJ^-bDP zRLgz$jH0RjGpt_vYx{D=3LcO;_Kth?>(U*W4wOniY4B6I16wq`?9Tk}X!wTMvtO&nNK= zp~SCdi)rxDA2py-HYF*JGkXeXTwt~hW|(__$HWu339TORFN-^o;tnm$-gLq5&gc;r zn~R{;g<=It1Y=lqqOXuBuS1QlLP!}X8UjF$admZbdU`ruplS70x`IRJTN1wS<*E2e zPPEMxn3xvKky@?6n4N~gAMwX52smSeMT4c}z*E+DYtruN!u-8`&kipl{@M)Nh6uGv zzZEO9L7d80Y6k$6=Anorcm(?p`wy`Y8Iuf!jN6C_kh=C%&IJsm4n8A@$vt4@6oTpdBn?MV9s>3oo% z$$0zAX63uoTZ7hxSaC6{N3R<(_m_01)e?S$4!wCl`Bvj4okA=${Kv`<@o5mpmhhAj6iHkpPJ; zD(=2+jhpWxFkh+lI;IleD3$&`qe=pw1FM*}4hrKMI0 z=grk&$qRo&z~;*xVst0D8&JO5_gT8g%5otmk=49$q8)Kt(=nLQPU}^iz3~?%o`JqZ z1!pA;WqZvs!!GPkwQXn4ERF3=kl#iLy=IBo??mr5tj$~ay%B}T03pBmD;Um?))@mgx_(i&v5`FKOgVHbA z+j|P@Mjc_x^seR}K(&F*sAL1}S0~EuiIGgQN_uSDhXx-G$Nn>M)%P3~s_ISPZntpX z|F&XdrU_SxOzfeyD~&hRt6!h!+!CzKJQqKd^ax$~0wBrp2#Sz9$hh~jqGc2fDvoUn zZ;xlo#JIv!_QU{B{LqSJB;@m5*w-ZF^LTov51Nkrtacz_6uY63hdwS@cF>qJx;po} zlEWkw#%NBk_iU8h{Z*T4wM3_nN%yzT$eF9nq`+hMPiY&Y)&ZmJ+>#g-f!n0QF8hyl zxUGZUMvG#)?Vk4W$dAWs)m0$VJG1>|@@BYK6{*R{56=htVg-W_l4&erGDLlmc4lfc z))75fFwY>3!8P3l1|I3YjwiYNx8m18YX@(f-InL`AlHVI;?fc%J{18 zIosK>MobF?N5BlfCv#!N=!$cau@o?Tqs5v&NyYFm{_;xe1xP2nGgm0rT4M7nB2Xd} zQ+&Y6HO(%Q+R3NFF6A) zbnomIwdH3e5>V{4O$Rs^ryO`u0`hJ1Cy65A-l)PPGC@RQf5D?WtUZQi;eY&5Nbc_? z5=myQ^y8R65nwRzCa6|ofMJBYC>mO=0}dDk(3LGSnBKO-#28xV4aRzc(Rgu>d`a*) z^rZDqUQhq{!0Y_vV2v%f3E2(aP~HF&uPzi~2I~(-@zE%F?`Rh5Nu?5ykL@koQr-XY zMKSu$t#h2J;$TKY06?CyOmp38Zx?*IZRdV0?X3^#Lcxm^*UHAkia0IbDYqERE`L?g zIQ<)#Zb@SN2$%{!Tj&$NH`6@UGcVgpr>kGbY)*v&a+50xet)uqe~&2EI~ovX(54V}F^HX6?x^7^3M( zNpukzgo5@lyrDip_gOM#!d6#2rj-PYl~66>u1@`+tjS3_lW|GTuEPxmgb9J^qvAzg zakm#I6k+IFd^ElnE?Sp6&pX3OWv*|I^10yYZ@t^fT9uV`w z)qAh0U=TBzt3MQ-I2=Ac=E7TZkkK9GPJrmO*K&sct}&QfGMKV2NXhUNJaC-`1ymLA zP>T4perMet5{SR5M*3j6lNFG%H9GxRuD|VXrg&QC_X}|~}>CSinM^FI-mEUJ042LI*rX`k;qqwij_)+Gyfh4X4 z@WDv!?hU-zy6c~69d5F?k`GBJ0m(*UsO|ssOcE*8u07I6J3My)OQ3N2C2AE5APNu( zcoBhNqjs4ZWy~sYjtqq_E9L<+pwCQ@78a2KR!k%Ho1+=a)w9tpZKxJ#!}fgqTN~Df zCX{YpA&x3=R9B;LIvw&l$wuAtY@a$u=@Yg9A5@CXh?7bIuBXf~O!$q&(SJv;OBF{r`ztGg)((do*O zqz7^ZucM;>(@lRg{;FUw-TUOL1t#wNZbXgeYm&k_4wt;?Y{MkHZ7hI=w&B?hstR!T z=3^vlRybS7K8&h~S4ZIH$csQ=BJInTBg5a=Fh(>oWy?~-pdmL_sL_*BRQ0r=8F(Jt zZpHQ+Uu5?Gzc&r#cI+(=(W>xb=e3`+8X%A{F8HQV5+&#=CIN<3WR>DKR^bC(!SG=O z2t)tQ7rgR@p&ewX40cDMpAS6`0lUf`P&@wcYEK`;OH`XctYWN^thFn;RHnWGdTN0> zS^3w{5XA3r8*~Nzhx>-NasoLF$Z~ygS_=NYDX%>~^P5eyc}I}|$Ak7^FqS~@8|WGU zjOc(1Kadu89Qy^vw$K{h2!HQt3v-YKtHQuY>)*QqI7Mo~D+pjx_WLjQc_RYi0eEKi z{R6`5(cG?3${a~BAvK;``z07shUK{28A$CU?0bQCx+m89Q^?)%^2GM)WL8nH!3!O( z4FGKw=3tME%V`tFhkvwsm2~peidpP_*6*09H+ySG;PsZ-uA94N^#LZ4Z%y{Lb}%q* z*ki$0maET1|MDzVNpKbxpJbc?>F+J^+x>!_(I)>COsafQ=%IqgqIbvhV6A(cRSb;E zlCSkTCh@yG=HoHMrCzzYzVtYNG8?q`MO%(!QQOV&%f4fZ$9ZZddblJ*37l3XL8z5dkz5rd$DK=JjaKvt%Waw7l*bj*tAFY{mKw zG5LuWXKpgn4G(aEhRoOnEQeucYtToKWL19hFS}S4^l&p6i&S&ZAE+0oONTsPO)@I8 z-}56AbU|c{NpH=TiLJ6H7xNQ_4rCC9pb|>L61v_!F87_qu$iyK2XiLX8~ilj5DJxA zyaY*=)4)rcGdEm~M~37{woyO4Cjrf#$4W!uS};1RlDx65>Y+nI{yHV_Cv^$`>hk~g zowq#Ylp5Zh%ls3OX?_@>K-n)>QSvmhSwL6j>zco?;*XUn&wH5I4^*LXUsbkv3&qoQ zG75Zk?RDa>?EoM2=?=+pZSa<&b93bNSI8305>iaT3$grx-StkQc2IfDei&*(@QS2>Lf-}XE7!=?r5QIk0|*8kvM;nWY{Aafwt z#|8;{VF?UW>fh8p2w8{%CqQx>eQ`^mR%AfTuIn34%4e5nd-+|_l6bO|dI?St!MX$m zB#mu7H{fiqklu6ogK!c>F0vH;i%W>a5vZPM29?FHjQH1^P-98e+t}H3MYFx4)o>wo2&9izj#{fQku@bsbq&z1HR10bWtqf z=^MpZ1@Lo6mb(9Cd&lI#622gU>W>mY=%}X66npr&+I_#+M7-T4B2HC}0Cjw>kCG>| zqd`!v^>w_&W~!+5lij(x$YP!Vo*N{n z-I0(%YX>u5n+_b1^rSIKyx^()qLzJa2!gMorxh=AV(Vb7P`49u;v2UOn7b>;tHoqq`K0@m!hH+4Ak+B%If zh(`|r=`2pyS@~o0J*^;npnuC;m-(OWVmgracJReA58a}{T^*WG?vUxgpIcZHYw7SH zb3X9D1llF-Lzlk&2QX)xeKZ8y_zp{gA(H!}p>LNj} zT?T>z&p-KCRUZuJJJ)Izp;#WbJ@eWDQgyb*XBGG&M(%tpChqR;@GJ7?&+x#Xj@ugB zyTY4g&!o^6MZKLZFdjhAQi*Sfo3DjMPxYp(dm1L9Zg1;OX0&%Io`#Xb$&JfW@@3AK zb_0)#3@TV=s_cV+(#{mfk!qbUi_IsxL$pM}QnC^qJCFcThG#+NP1SpNl%bc5n<1$p z^S2V>isdo==$geD~mkBzTNGFhS80ItGu4Z85e&VC1?ekRB<% zZhK24wAL5SqRyHrU9?&20>hbTu;~n6$wlLQMTzqOADASwJ%{hd|6-KSg_8}%ZPi6W z&`TLf+vV#LjU5t8wU*bCQmwwBTnLE~Wc5v70S|B7T21OJ3qH1hlNp(q*Il5A37Pe* zc`Ubtldp1)0+ooT33&m?6K7{{nqv!G*+2i{fX|_V2F`(yocHnEU%Zi+tMf(1q!4be$Q^={NE-c5DZoExCj;^* z1mZ;D_^b>zwzlz9#&_YKE`Rikba&LR_;FEIKw1lkv`cnaI}%9a_e;oES&N|=L<}U>xgXQtNDUz}kSBcGf92RWQIc<~+F4YB;$&H6b5XBCL?5{-0a`Ph(@k!Q964}g3|)m?N&IX#oec=ydm zQ1;Mhu<7FS-qUGg0uZar&0Wutucnx+Q|L8Da)|Bf(8q{lTkb<~+{RWC_2rlkgGmvn zouE=V4yg-27@NZ`L2l&55uuP}&6`;hyYXH?1isE<@7~BeY)n6t2efydyHS$z z?f6T4uUSMT+bX@3csN3Oy389jNAY7@KV=~#_kAh8VkDWNu=lg8a8oY*8)I68BEb01 zTq6bs2V90c7>MHCu^e&}{XK$?2>=wwu z>x?jsTWd&NBOMO|-45#veodC^-4p@=NrKQ~&Qyu5OuVv5AYvZ4#S<7iQ-Qu%0e?hO z8YUDbXC&q#rwRW&CUq$*3yO>`nt9tX1qgXa@21Q`z7-r>ak?Jv{E~slNYwxzSe;5XLMz*blYH{OJgO|f$aGO zD&oHw1h}>od-k@J3_~6cuq&nK^Ir1%J5~kK1RQ@vWrQli2RugKX;>xbNDW|+idm@O zcZvHjfIYv|ejWr;Ckb}mKkZ8sN+Q-wr_BMd#NW%@&u_eOtVqTJU>3-OD-8MQcnF2a z=)Yn)44c95QBQ26nmH2>+~F?}Y&C*V47>_~b|Eu<{}+grEKZUUWW;XMPnJicy)RzL zgkzJ3N3M6oDpQ;}ob&oLHFb36n-oJvvfF02T4-F~VkpFSym@y1laIo|6o5rgi-pQ9I=>9#*5 zg;#XD9P?*AbrLBuL>61KNSYi!4J?jxaXk{Yp%Sd6rP)dF)5omSmCy(W1;wn?k> zi68&-f!hbB zwWh;N7(@JS8}@J-1eVK&@sr`hKwH2B34+8EfnW%AIk^F)U{KJi4ut(n-b1C2HAOWXWH2;sQ<0{vk0X2beYvEVuUZJ8h!lsdt)h4S~e4HADP{echZ3I~crErk# zS|$IBZ_GC$ZlZCJ_)IBVXa*0O%F5K@)@brsgE*^4lP5=4gu6w_qC?e5SVlhueoVt6 zY;y-PRg6F*6B%L8v0$VcVS-TlZi*i_JaV-o2P%clrQ$Q@?@WOC-nRWCZ_x3z30+jE z6Y~3&i`sLKYELnz=$(+lpDE`9x7+wJlUr|@%1l0AEsZ0r^$L03DR;AvkyXiF9F4x5 zGHieNafavVr||3j-8pr-?-{uBVt$Kyp-Uc>=H6kuI3LOI1jIY>Y(S*Sv|wao{&%L= zDf4;==4OSM%EXZJK$5ly9X5usnO(ML>SQ<+HY8)VwaJ!tc4&Lp49m#Ohtgwq^}Sbq z&bkArYInXV)Lg0P$olnsIWrO_d4TkB>N4Qa!Zi~!mDVAk{O)B-0Een9cORz$^&`vn z_V(~MPuDk_p{p}k z$KrJ|oBrJ*9X^?Ub3f;@_<;NemMn=KaloxUFn9jILdS1s`GAPUX)djn=vT@_oQ#ZK zA|3{nlVrsuDv#Z6TaUH7qdyD@N;Yv{#iYB{t3jBF-yiRZyG@it(rngn7H1g6B*83K zvP^tZVqBpfcACu$q4LBIO6gIGJ7(+Fg8Rz=S@jCC=eDV#L9bF)j^ity*{M7rjh^F> zD_iM`>45M#Gc}8Phqv@sJ>^V(ec{PutBuBU)FxFUPsC}%4G2zjAqn>`F_t&Sw>Ey(AkRJ0lZ?!n!_liCi7zp z#FrYZ(N&z~9g{uCy{vc=)7Sl_qnRnf&uN};X3bvHS1@9zTLmRwDlaPc$ddTiMKEr; zFDcAYzofzz?~U13e-2N<>O6R^z;1K*#VPgr^=^LuL?%#*2Lt`oIxJvH{OWAO35MCKcom zfPN1IC(e9!i@uOXFLk?q4j8)96U%wJExg?Vv2Rs7)Z-(&ra~aU+X)-KS&LXW*?`a9(!uBamkM%m9HDp`#nCCz1+*5( zAF?;T$$2ziV;PVO)1xLbJW9|tH#)mH=q|B02$YNw9Ew?5&mAiNkblcy?WC|B%A-== zM`^JO4SsVdZQ}Z+)%(IX5t#RGB0RdobC|OPvnF_EcRqnrcz%wao(yNB3VS*m4+j_{ zVPf%EseQbrE`QpIjRk92p6VIt=z)%4>obJ%_fh-Z9nQZ&-RsW=w4tFYuPsPPc71gf{E!Yoy?duOO_q++&eIC`@m z-K0XgONZW#8X;w6A9iwrZ;7JEXUE$YlP=dvbTv8;ghC&le`y zq?wDwDkskTbem)1fxVLcMFnKZneddrwzV#%1Dp9d9{05;DrNC}+wR=0{?DW@W(aEh z^+=Zy+>(7HugtJV6BREO^S2D}^hKm7a?eE)v#*xaODl!~6ni83TyyL-P(ik}czLOe zV5gZ0G42aPT2Lar=BtUaQ7V#njSjinsz9C2yBPbV^z}EgF1bzo}K48y>-Y4jsN$Vsz`QIaH;amZcJY zNW|(CRyA{K6Yev59T9*MPpdzg0^!Q!7<4C%2A)3)x;BkP(!vRxt)pRcT~4(GNAjenZjctX zxi^~U<{DavyzIA*4bB`y5wD0O8z;EqDRd_}`L56vKIYar;@K6BmQJS!4yR4vbFP4( zYlI>9?panXkk$tvw}KFp-Hj&G(S2Oj>xv3a7tA!gS~9(atqtgEn+;77Fe;I0f3`p9 ze0^XjG%)>rU?|O-t4D8bt>=s@RI^H~XYM{%nQcD?nXm(7v1?bT7L~Wm^j8Ryu~wBA zKAbP3FLeBLlRJNPhvfz}_JVRwD_(-H8jGV7mI9>xMn@1wts1v`yf!+K@0e8~rd-R_ z$td{!y)z`Bzm~LB=f4+-Cm#3XHkeP(4PG!`pFQ>t3-7mnX_*W2m? z{Jt!Wbdrr9Wuci2+cI~hafgE;*mK`*0qWPJN)i|F@L{kt6ste~5cWZ$Mx_I}zy*b@5I`DmTSn95rk>A${s^ij^q zd&cQn_z|yw%Hg2sRT5|PHe*DpUH{9GJvaRIW-Z(SgPXLEWDIDv3vYQ_AZ1vPSp!Mt z$3k5DOShAl^6@M9rIn?y)YxQ-jTI9vDOz!xxX<+PN=hK zq7Qu%O(eyl>6xwB11B@$X7jycQGZS*T&|hpv{3IlYw3-D&$;DGL7{qNHT>(1n&5r# zS4^$3jqBp?+M#<}S?jp6TsZqs+tBn!aK2X}B%W4+>>f6c00yOC1VYdS5~~xmZ->d+ zy3%$W8}v0$9vAU@If0WZK_gk`_OS8%;OW>M>=0?jsEjBHnNw=*1G9q$)hl9Q2f(MD z#*pbrbC|AuPLYn?W7h0@`4&hs<>Mv3Gp^}3yU=SC=|%1c@d2-x748QPO6wXgm_&Q_ zc`vbpS}0gc3&2s?+fyGAqo{#?pGaq0{%#xAV@c>^yiZIQuT$wo3@AlHGj=m1xN&=Q zvU)0#YEsVZ!%^0yzp8GPu{+=Q@!MCsWp%VIJo}kTdb+;~i@d`d4^%$WwDv=K?>|!W zGAAxiPTHTrM)WB%U}CXY0zQ6M@AyjdcqgDQXo()t$P~X1ICXDbx&N3ibph!rk}TZ$ zj^fE3|F3r%MG+c=?(y;6*%`c7mUxG2^j1V z3fg+_3XV}l=u0XNmW`)b87{l7^GW$t565YX1tYNxln|k_N%IdyJk8&Ya#U}_@Tp6W9n7&XcdzR4Q+w1#$2;2 zvZ$!vb|hOeyuW-B{1?O@Ped#(X2PYBz=qI9gD_b+%5nbGigBc zLv6|u%%6N1{1t-z-i9@Oo@&eUN`I-vd$hyps+1%WMBLteYyq7+sp$bose$CS0sZ|q zxB~C-?<0BMX=%R4n2vB+|FloMHH!Obd*Rd3Yd;zNtZqcIw1E3{0Z~bTPPhSyxB<8; z0hESgpNWitCij8XGZ*yOWQF+6x!lP+-#-bFOCX{5m`@gY#b-MPnb&$8v-$bl28N)% z|7`O0z~Ot6YK~fD0a0?X7E^3}XBfr3aVxcFMVrSj02S)!*Cc8r0bAD_&&b7Jug{X= ztd73>&&jwp=~P%;<$HF{U5#lJkXx%{WO*$8kk+RxNFNW~d)~=Y4o=D#SvbOJE?C;0 zcn%sARbKBepRghnfpfB~JB%G`N&7!V%uW^qjpG5e3Haf1C zE7TD1@V#d<49M!b+U&N`Ymv)IJFJZuv73xSSWzCpUt7zq*4fcosCQSN*E#T>2y)ZN z`RpkHyEVKB z%%~UPWa3jybBz0MN*eCyrrasRxpTdM@c+^F7Eo1feZQ~>B1j`8ZaS3?5d`T_N)YJ= z6$PY3N>aK@(jcWpx|FVsgksRmCKRMpI_`g|=RD_m-uvGBe&6`MF&G|??6ucgbImp9 zKYk(E=vyivj|K2I+yFp|NL_)@C;Mvr)Y>{Ws24Dz=;*T1Onp_=)*qQkH65{iYj`zX zMNFPvb}f0wVtSp^iH6jd_M62@l5}_6{#V#Z zm&Lse(|i!Ty*I_={v+Gqg@N1Ap}+8XlT1#)dYrSl7h-d|JCTcMJ(IcEhhmrx@?t`% zUKhM;vHt71!zKJXEy-PE9&J4syvyPSwCXT(ri+H+aUQWr$IeO#&xELA?r36D${uKK z=Y^qU#~e1ClV&;?U$>F*UT-yqKwT5p6Q}J$2_GmW8yquUJ-+3F_2eve;6v;eidak5 z$0jfPCMx-TzwetJC0&r&w5;l_Pshw6|D(40W0B-1CpF^oM|g8Lrw`)J(I>w%y>!Bn zXc<5<{OOZsA%(Qj^pZgnm-n)?pUfk0<4cvRK}fBwvfHT$m^}Jrw`HEcsnsa8)!yIO z?1-H`c{7bAI65d!ezB*gm(RKIQ*lD=&dxgw=?xm6kw_w~;-2d^PHiCMCf%&5C3wot zb^wD%@|Db99iWi!7RE~P@o1QxZZ3VKb;Z@rfn0`lGX>)F!e0pCT-!c3K zIE|Aoyb=}lS^>GMqmv15b>rKWEjy#`ZQ9)I?Y-7JI#Mojv2ha2-P1NLT2Nf4x<|Fk z7SOnkY~NOymx{zbY80qm)%W4#PF;B@Xrp+N+prYx?uQ(i;p>#G7I(5broNq5oVHld zfLb(}vV$-S))5XNx!7)%%tRM^$48#4?fbW8<5yWEnr+0e37 z1MMP3M&|+GoVHc*h&!w`WxOYvdiPc%R?f)h8Th&BUt2spIC)2-6Tj4=y$u{GOYPrb z0enE8K5eAZ@*?gg!+EPksS=W>slt!=JRMgjyhJa}2lQapIGk?2eM%Od*ryc78oE9_ zE2J1n6Mp&iR)+FtWg5|J2D|Y${@}RNBJfahu09M4m^xhc=&v98O{=VuBYI@6Oi4k@ znuds#6c;CgOl+l3|FoH6^vP?ER`bdfPo)AW%%&+7knyI_m&E$=v_K`6 zS?5CldaUbe82(k@{I;}}_wF$X$~Z-@`ukinYI<=PuQAs`wZFSdlyvf%!bp&IOrC>X zQFuIoe%%GR=lEWZmMyYlPgWmYx)y!a9289!Im>OxB#ml$2IH(Oq~t>>PeWp)5SV3? z-L$cb*7vM&JH1(NI6Y~(;8;BC@afINW7WBQ!3*6Nop@dmKW&RmeP))#!(u%)=08j1 z0om*XDSj}k)Be>lQhy~3H*pw>DM&X2N@Tw(W!rIg>-SOK-oe{hHU`|wJ=^6I+ghV3 zcVC_)TnToypX{1xFHqxf8f)-UipsZ{S(w3lCR%(Q$wgDe=^&zrt-eA8%s>??p3X8h zE{B0{INpc*q54Ae>2~#(5ZWW`*%3h9Fsompg=Qi3V6ll(J??{Syctsrr*2)DM8VeV z9tnc*q~uBnwk&?iX`Fc+fYO0L6z?u|T^-A!R==?|nq$nxs`{7|IWCo z5PlWkkvp406qVX2qTTa$?-S9Kgd-uZ@tfm=kxyD}Rf*+~Hv*8WIhoOqpV2G=P4>x= za-3YAJs7>XRw1dz@S!id5l_&0row9oD}787CvQ+$`*z-lq|e zykD7?s~}hy|G^yW!z8<1VO1>&j-Dg|4%f4+>4qC!##0@hi;DQ75uuO@i22^ryL=n+ z?@lTm~8;HWreqOwKcA`Tg3Rs(&Bm8`Fa1`z3Q<_8MN}@ijXmU6AbwVl#@yLm z5}|)J8pzdp8%7U9Glb=`d8Xu?f`FJ#fx(=H^^!zNJyTR^n`)c}UmbKL4%nWOifaqL zX>`LrV>swPo3{elA)Voe#6(NspAG)q{<+ihZ3;{skJK^zievAIzDk9&WS?~UJQ-XQ z>+lt7x z_mL88#}t>SzB$fqXrsg*;9X0T_#BQ>qpfU$inx>fGxYSQ3bGHm*Fa;|0YPI0iVIvjp&Q zFW& zz81p5E~ez7)Ur?fyDN3zyAiC@ve0=ARXD00hMKw3-Ta|9#=e6zCDJilQOWa-$H@oJ z=@X6)Hh-`kI4019&SY(m)R$qCGkOb)>D0SeuGMVU8Cx4FFBzPn)s;onV1dihqvV`Lr-k)&h&oi7F1zz`HIPN zx%FDYfH{>@_`I!Gef`0yXb+>n7!*?OU$gu9kY?7HY0y;+V`Ct9;#+U}7&o1;L2%aJeL+#;Bcd639=DgmgR*kzz zYqTa#2afp)<&GoqWFGIx#Wf_G3*z(5fqd2|L&l$g2fGPtHMKO?v~D{U=>-Vi{g@6euQY!`?zAmX_`dV844d}i-H>UP;D9fV2{LlK zv#r6=dZIq1rvyjhq(cCB77!9bcZKmLc;KR#qBj=k@i*pT2CEKtH%tw(MZ@Cq9C+m; z@3GjJA(pI%PdLfX7keJmhZfqj_ft4N46C_45W{X~7fLIh z*gzFrLZ(j#ZP-N{&j8^lWi{d>=3wjI$jNU$rqxvTRHQZlKe!%nu(S1dsrzq)#aR!& zTitfi`9ka&PCH*S7~1euG(&_{271bLf}*2IK3H7|wz`%!3+Ngj6dULhZ13*~txP^7 zwUuHTK*V8SlWz^D_Dds))SG8`{m&-5^_3{O<1&yIG&lX)QHWz(-{1PG5cRlydgonZ zP->vQ6jRYBu-p}=D{MW`S@X%*P1E@4LaC*_Umb7~U_@UtpzIdO^b2vq=6O=^u;}71 zAkotJUbW?#uX&BfT&g>J#gu;A=Zaa5C>da6^SDtP)xAJ+>~qg&E?rQQR$&gV!B;Ti zcv$4UbxfaO{&+HU4cZ={BVOMhppm%cz#MGn8*?h|I>s%^Mg({EcIPAr1#1xCBfIy1 zLOenU2|lxMSr?WN+Bn{r>rUbWJ)h^dxRVPj?m*q5bMhEZCRm}TSr!5D_;?U+H zL*}P4TFL3xPMoFJ6<{AZzV+g7hz@xJ_8Fgnv%jEr4@R8tme|eGQuLXQNt`xV8deatcvWp>#Q|%@OX#_~KmP?$A}<@J`E&oT{((!nHxbHXRt0Un zOmBaWI}_OnCyEkPDyU$5i@*|1sRsGZAX9D38lOwZkxOZ*wqZ=5zEHeeulet(9l!qx zFHaxwIEa)U(hJX`VSbXO`1z8#P&#E~ndKH$N;^~354iPO1B83s_cK0U3ES~9 zMLI!(suYC10k3sR@$PV)*akJa+W@6ArJ^!=9Pn@7lY<7%UiNUlS^4e}0^Z=tV0L;) zXCoGK(OzCLy=p6*I`+qt%?~s@(-L*Z-uZOhAdvbS5w@Yll71V&XtN8G1`?;kpXdO! zI!gBy$f`C`UAhi>gQWnQbI*DUitaql)J9b=kQ6*(p^ad_(vTYaU|?{Nntp{|uilzx zz9-c_-&@zj6+DkhZtfhH52L_`*rf%K2#-4}Fj$;UoE`wmA(xiSK0lpxB|9h@L~Ubz zQ^gvOehs97>r($2FngDKMSsxZVn%?vx7*VNicJEy-#xYRD_n@S0AS!q2eowcjRbFyKyZ9*?(9@L z^!}7Q4W?j(GaMn&t0t33FRLTUC9zT5eI8H!*(HD5;pJFKxl4ENFRrpIj?YRx)T|tK z|De|vd6s$x-2-6F{z@$pgbn}<-eyqYE46Mn_>`wj)D_Rs8oer20z%`2XM~OVVlSG~ z|6urZa=6?|4ug(e-|Skb;s zAl-{ZMSP-5;E0#0AI@Gz-wtq(oD_Ngtd6LAEK6}ARu3U% zxlkj^doB}M>$B13mX`itE0Ez3`$+G#$1~5JVuSiqIqGR441fTFwgaLO>~!hU)WFNp zJgqFOAW-4T>3!w^@hiyFk=*J|P;8OMM`YlaM@p4)cEdKIgn{671H&i+I0wpI-+BM| zIzb&3C01(w-Qe7FTbJ=L9Q@Pizz^Bp`Oa}_j*GY5mq&d6`pn_M7E!V3Yd^tTDpv&% z=KggDF`qBO7HuI>&@8&jq;S*R)9nZgq%RU@>7*W9*>rvFK$a%uqxePe1;!iFZRVpv zADa&q0(F~<0dDIv=6hAo^vdp>VOOOM21|-AyOp#t0noy^iB87)CSKLt?PK!RlBd>5 zoEi4!>(coqFGO&OzXT_~OjS7>E5PzK9j{qY*im({<-|oycbe`g)(eH76P7DRkT*W) zuQz_yk>G+SJb^HrPdz&a$dgdD8n>6W-{~38_qzB|EweOsfiIPZk2P7sF||XdV@_Te z7GzmcG5LXjqojQr0gEf)5F}(Mx2Fnyxr}gZ&RmSp$+w9Gh_E`E zJ2J6%WM(<#{>CkD5bNA%_W^<64J=JODxkT>pCJaUQ(|U-TkX5VVX_(TF8~I)YA%h3 zlZg<;K}Wv@R3b_rE|{Ei!V}0)?F!r2qCB4vjIPmZaDG9d=<;opeb6YwR(t0m6Yq_@ z8^nLq6)3ijEm{5;v>{ z?M>tKIcl9SgH{!bHF*7*kPAA|$+|&nFnNL<)SU8k@)LUm|AKf;4P+#cK;EWs4T6T_ z=wMGaPtU8mtx8ZMyCU8DbP}1(O%((2IhR`Z2KfkSr?#Hj^!B>X(8!0>YzURyRWC`;E3bBCX4Dsi2-0p%XF>h&l{VyNOrTR=IP8f0FZT3t>H{jl(I0s1RX3#3w{)P|}a{1cwvG3C&l|FYkiRFIRH> z-ofL}er?d>$Ja1*<4b75_vA2S97(+OIh3aJ(O zFVIZ#q)b5}>;p634hTTBDds4RSqTTW%RKZn<_i|bHP`ynMo3j@c5CPJ^;x-w)QkUh z2TRKskX>AJ*eZD&K^)u6G;xp9frgf7*@_t6+(#Kj-55M&45_xiLdLts>Dy+Uew`(nr}cjgyCX25H$^C8wmI7-(Jp?Eb&^rXMg-j(nS zzY#qa+40Udf#olJ8N-q`zmCe8gfBI&1d^VEa=|0E@Wk1v!$xe)Q&%yhN_KV=_2;8k z7jXy#(23v9G8L%rNfpb+wxSpwM81RibeD|h744SJSt{#o^t-Sf{ER`LEOghK51F=#>9$=3;B8+P?0Wg2%(I%P=}+>{e|@slnrLFjk>F{eJNRgt&@ zG|t|?ynoGWx*xVv^M%dvvVkBdiPkK-;6rIdI?cQOeX*R4evR{DI@t#9p=b@bYB{Hwny+=6 zQ8P1O5kSK7n@XRRFWkb)m^8e?9K6_gZ-E^GO=cn0fg+P&1ZiS_Wa4(PYkF>F@l^D6 z4FB3k>)vr#`rVUA^8bppijvdH_s)h`KCBZ#^9mFzeJ@nYN$6OWx^NBQ3|PKY5V*cR z#$(;DzwxtdhQYJ*8VyVI6Pq2;+R{UFpCy1fumFEzY>}yqc>kht;v@6~XY#9LZq=`4 z<_X-q1vbpHvJ|xSEV^oE20Q7?^xP?^x~j{g6g8fEAoq2n4u57Zbgd2XnOJ zqTog63zwW{!yo0=Kiur}^Ezp6pGIluT4&L|p^ZqQEoX`sGuzpdRo6s3pl1uD9^cN4 zt{J&IG!k7e0RvHUm!}wo5B&E76$To z_lmkQ7SBY6p^*RT5(q57o0o-t_Yb;)jW=KD(k-RvvrIy7{2%s-92F3zmBwmeN6=ij zVWQV$V?ngg@q8Y-s4Rr;1Oi#oe*3V+pHNS`bk^*q4iCPZaT%s$M;nH zK0Tkw{^=$O?|nB;oi}+D_W%<^yZBYla(-h{H-rIV!T1zDg9coYioMe=6k<0PvEJvQ zGitcXQ@%546I}rR3tFrTzsWm)cwz6zw*y@wXBIctV&#B($>q*9U8ws?PWdh`~?#_}uF+@=-dyqp41`QTJqF<)N6q{%fPW z!R9GpmjRJ}Q8E;56&4J9#f}c~OgSDvo&m1OEr8{ii*OfpQbvT8P} zhtOqqOaLkFmY3wq3M9KU-V<><+^?m$xH8sInDD}pj&)55u1}bhF*C7qZ)^3I7qLh; zcyP$|+y7%v3igCODeWI%eO+-A@@o39B4S7E@a~bH8!l~Y)<4e<1Zu@AZp>4});s<{ zudf-LT43|jK$4X6w!+MQh_NN7Vt^u2@yv|ReeHdpSHxwCGAyiNAYF`MwNvwEgmTOs_xPsEftB6|W6kC9R8&<(A;grje!dz^KmcDwV=z$Nk6oxpUjB zX5?@us*e)<6_GHF;<9?I96lq%^@O$cnm}5~jdBYh+E6^R!J6OSlY6aBPE8v^fPG#& zKLlV@v)lcrMZI>5-lR`0>0X-)gf_9i=ZTGsE3vYingybso}MN4@4P{~%FraPN%451 zDnJ8p-%tzbsBZ6W&+Kg-tz>RBa<8|uH-xlNr*0p&_(%`Eo-oObU-{iX)|`Jm^^#*8 zSftgZ6nvVh6Q7bHWs#^kA_dW$X8)7XYs+7R+{L^1Tvw;3r~T|F-(dD0x%q_ri|oM3U`XT>xl>9X4v!ZgSw9K` zlfN^W_G)6R{(?S5gu^FkFT(gYUJ47y*npiM~*P!%>uL*q7Y=e2a=fH7%KB(q3Sbz z1honftwSny%`6Xr2qqLnM1L3awQ}&XWe4FrU+U+{^C5d43mMyzdyAOs^c5%|29z*V|rmL zsyxOD^f<&O<2^e}C&gU_4yQN!3v6+0*Qln@VJmrI+r}FdU2~2Ji00=k6*c$MY8*9SwRR_z!0_@KhCoWNywtkg#~~aPn2la+4rprw4H<)L_&Y zvnl0s`1pa$e6MlHY%Xz^EnzhQ_4>|ttH-=rr=U?PeK@9oISTq@H`&-Rd!9+AY;)4) z25@72+9@)cgFP!r@c!&$;EDP>fyn>ui7J9j&kuZ;VzU4fHB@RvKriL}2Q>>~6onU<_U`#5=+EJO=*g$#ed-$TMa(eDCnN_S z%~5+E`f(w;d3>A>h$%^4S@NL~;ktdzor5Rcov0pvpL2GW<_+ElxjuZ4t#9Y{LY3dX zOs#J35>g@sB_WC)UDex;Azay@)>9yL`~J5?Qr?CuvGN>FA+~W)V(peh01=^a?fjl- zPTR4Pt5M@1`QrR-;%XSTtSx@NCI&B5182J)mK%<1B%ckY4q zp#t%^tjp>cS0|m&VWXkhSf6Pd*iD{uqB-NLGx>};I4*oA=2bv6-xo-NqW3BA^HRR= zA!W^9UO=?JrhOrx8hsAkLxI#W4Y2ep$($KIcBJ~m&7r7Foz6u^7Ke?ta{!sv?Bfpe zUm0$c^D&x(Vh+?Db;H;)`Sb2%<|tL!Zu-e1dEA^Mg`;Qo?aI2{XLy=S<}EmjpBkR* z4+G$i6hwtn5(GRKIe~RgH0pXU(L(WYp5_mImg*Jbgi4VO4EHg6dxpDQ@=4dy#{4P8 zTvjJRAM``_PWvVK?&mCLg8OT+QA2^0q|@QdIYa`IZuEfyR9fHrXqcWe3z_AgQ`Sx#X2@L2 zJ5r4@0G0oi>{7R_O}ZTQ6hE*9%aqG?fxc`(g7pkgcbLdQeubHNX*C_GOgAA>gVuko zivE%(8$rzBt~7@1k|UMNT8Qjs+NDSb>%;13Kn36f^^wtQ?-z$I3EcXEmP_ioHATkJ z{VW|_vRR;_nMTw@WNyHj(jeN6`R!K0{k7=39ow+w;|MV zFAqh(CB0Z#WL!;N<#I$RM=_()TkzmTGE*wAp}el4+`esVP9?yXg_`Qw_!SzN8O$lM8J`_?};-=WmWeo589J&D{SjMKYag+{T)hoR_`Rw6u0&~CE2m&{O8>M-HrIAXIOy3LOsULMV11}&6JuNcFhv_9f(R>4T@X1N)7 zG&|^*(?bN*32}$=L*W;WZtFrYT4FA4V6c@k(cQOV&lvUX%LqV*Yv_4`zHo?G;C7__ zVjP$NmR$|;rXk-Jf>|En~ip(|cq|H@@3_=4oUZT)yRog zBW`HIX#IPZOzK5f+;%%oQYv~i`|C>TjeN#UiC0pLtBIZdHcPNqd=$#g?wSNwAHOOd z!HyT5)B`2dbi?Srq0)OCNGHZfY@^#SA+cC5B(pti3cB(`uOCW*sv_sB9`D~3Iph&o zEUx*Ll$JJkC%ppN@I#4*yM(h(l~_Qe31MiwsrS-&VG+rnd3u9?x|t87t*;)vHU%W9 zYn~byyi}ptcM|KJ`d}z_g|Py8?GjPnt~4?Dt%12BcUi(u5n8o_u)XiL{SS98s!p!c z&7ra^24h5Pw%4d}U;S*EsuP%dm#V(i_L*a%Mr?`C=;2Ic`$-=&J%11>Cn~X-iSlQe zMSHJG?O7BRQr}+Q=TjKQ^g#nVKvcp+kc4408hD8ry3yW9JB>Z!Nd#rLZpM{{yZ@71rj^Ac7+rs0do8;CCy?UJ^EFw4D_GhK& zL~%v@jQl{cx5CWW;E4HnXxd^;lTedm!b@z+EQ5wSA(}_0Jw2I(B<1IW<)YsuPh6sU zi-|ZNUFo)$e2>ffG@vey+pQ$^-0X^QgLv?|+9k ztF_SkKHOAK>bh0K_N*#QTUJs7SaM`lqFh*~(tJ~(=1`ISV0dxkO4ywl(Xdy1G3mA9 zlHTh?I+z-fSw7M1P;#_u<ckW0gc4 zbE;_6%+gZ$qn$9w7+CaTEjw3u&`;U4(q&#dFGsQWK8+E%XZ`q`em^(Uf)6>cxt@6W zvp;`721^mUOJ3vjIVT+GZ3~(1JO1*~z~h0JJ%de2oE#5iMs8ZaImCpY*gJ@N+!jKM z-`8u=;$9B3YyFfCM)V8nWbFqXMgQbI%l2eZATtB7K6({q_#mlrrU*SmTC$r-O#VN@o7CB zEfdR<{Z1WJc@XZj^XkZ1uwMV;<7pR1#QZh#%*x^s~ZeLXoHB4y*dy%tR`rn