feat(event-handler): context support to share data between routers

[heitorlessa]

Issue number: #1547

Summary

Changes

Please provide a summary of what's being changed

This feature introduces a context (dict) to share data between app and router instances. For safety, it auto clears any data available within context after an event is routed.

By default, we merge a router context into app's context when customers use app.include_router(). This prevents common situations where a Router naturally wants to access a key only available in an App instance: router.context["my_key"].

NOTE. The same experience will work for ALB, API Gateway REST, API Gateway HTTP, and AppSync resolvers.

User experience

Please share what the user experience looks like before and after this change

Single view where handler makes some context available

from aws_lambda_powertools.event_handler import APIGatewayRestResolver
from aws_lambda_powertools.utilities.typing import LambdaContext

app = APIGatewayRestResolver()


@app.get("/todos")
def my_path():
    return {"is_admin": app.context["is_admin"]}


def lambda_handler(event: dict, context: LambdaContext) -> dict:
    app.append_context(is_admin=True, another_useful_data={})
    return app.resolve(event, context)

Accessing context from Router instances

import requests

from aws_lambda_powertools.event_handler.api_gateway import Router
from requests import Response

router = Router()


@router.get("/todos")
def get_todos():
    is_admin = router.context.get("is_admin", False)
    todos = {}

    if is_admin:
        todos: Response = requests.get("https://jsonplaceholder.typicode.com/todos")
        todos.raise_for_status()
        todos = todos.json()

    return {"todos": todos}

Checklist

If your change doesn't seem to apply, please leave them unchecked.

• Meet tenets criteria
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented
• PR title follows conventional commit semantics
• Provide context support for AppSync

Is this a breaking change?

RFC issue number:

Checklist:

• Migration process documented
• Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

[leandrodamascena]

I've tested many scenarios locally and running on Lambda and everything is working perfectly!

Congrats @heitorlessa 🚀 💯 🏅