Skip to content

Commit d1508c7

Browse files
committed
docs: middleware in router
Signed-off-by: heitorlessa <[email protected]>
1 parent 592d9da commit d1508c7

File tree

2 files changed

+15
-41
lines changed

2 files changed

+15
-41
lines changed

docs/core/event_handler/api_gateway.md

Lines changed: 14 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -691,14 +691,19 @@ You can instruct event handler to use a custom serializer to best suit your need
691691

692692
### Split routes with Router
693693

694-
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.
694+
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.
695695

696696
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.
697697

698+
<!-- markdownlint-disable MD013 -->
699+
698700
=== "split_route_module.py"
699701

700702
We import **Router** instead of **APIGatewayRestResolver**; syntax wise is exactly the same.
701703

704+
!!! info
705+
This means all methods, including [middleware](#middleware) will work as usual.
706+
702707
```python hl_lines="5 13 16 25 28"
703708
--8<-- "examples/event_handler_rest/src/split_route_module.py"
704709
```
@@ -707,10 +712,16 @@ Let's assume you have `split_route.py` as your Lambda function entrypoint and ro
707712

708713
We use `include_router` method and include all user routers registered in the `router` global object.
709714

715+
!!! note
716+
This method merges routes, [context](#sharing-contextual-data) and [middleware](#middleware) from `Router` into the main resolver instance (`APIGatewayRestResolver()`).
717+
710718
```python hl_lines="11"
711719
--8<-- "examples/event_handler_rest/src/split_route.py"
712720
```
713721

722+
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()`.
723+
724+
<!-- markdownlint-enable MD013 -->
714725
#### Route prefix
715726

716727
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
748759

749760
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.
750761

751-
???+ info
752-
For safety, we always clear any data available in the `context` dictionary after each invocation.
753-
754-
???+ tip
755-
This can also be useful for middlewares injecting contextual information before a request is processed.
762+
???+ info "We always clear data available in `context` after each invocation."
763+
This can be useful for middlewares injecting contextual information before a request is processed.
756764

757765
=== "split_route_append_context.py"
758766

@@ -797,40 +805,6 @@ This is a sample project layout for a monolithic function with routes split in d
797805
└── test_main.py # functional tests for the main lambda handler
798806
```
799807

800-
#### DRAFT Router Middlewares
801-
802-
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.
803-
804-
???+ tip
805-
**Router Middleware processing Order**
806-
807-
1. Global middlewares defined on the parent Router
808-
2. Route specific Middlewares
809-
810-
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.
811-
812-
=== "route_middleware.py"
813-
```python hl_lines="9 16"
814-
--8<-- "examples/event_handler_rest/src/route_middleware.py"
815-
```
816-
817-
=== "all_routes_middleware.py"
818-
```python hl_lines="9 15"
819-
--8<-- "examples/event_handler_rest/src/all_routes_middleware.py"
820-
```
821-
822-
=== "custom_middlewares.py"
823-
```python hl_lines="12 14 18 21 23"
824-
--8<-- "examples/event_handler_rest/src/custom_middlewares.py"
825-
```
826-
827-
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.
828-
829-
???+ info "Split Router Middleware processing Order"
830-
1. Global Middleware defined on the parent Router
831-
2. Global Middleware for each split Router, in the order they are included
832-
3. Route specific Middlewares
833-
834808
### Considerations
835809

836810
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.

examples/event_handler_rest/src/split_route.py

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@
88
tracer = Tracer()
99
logger = Logger()
1010
app = APIGatewayRestResolver()
11-
app.include_router(split_route_module.router)
11+
app.include_router(split_route_module.router) # (1)!
1212

1313

1414
# You can continue to use other utilities just as before

0 commit comments

Comments
 (0)